Publish Command

The elizaos publish command is the all-in-one tool for releasing your plugin. It handles packaging, publishing to npm, creating a source repository, and submitting your plugin to the official elizaOS registry for discovery.

Overview
Examples
Publishing Process
Requirements
Troubleshooting

What It Does

The publish command automates the entire release process:

Validates Your Plugin: Checks your package.json and directory structure against registry requirements
Publishes Your Package: Pushes your plugin to npm
Creates GitHub Repository: Initializes a public GitHub repository for your plugin’s source code
Submits to Registry: Opens a Pull Request to the official elizaOS Plugin Registry

Usage

elizaos publish [options]

Options

Option	Description
`--npm`	Publish to npm only (skip GitHub and registry)
`-t, --test`	Test publish process without making changes
`-d, --dry-run`	Generate registry files locally without publishing
`--skip-registry`	Skip publishing to the registry

Standard Publishing

This is the most common workflow. It publishes your package to npm, creates a GitHub repository, and opens a PR to the registry.

# Navigate to your plugin's root directory
cd my-awesome-plugin

# Publish to npm and the registry
elizaos publish

Testing and Dry Runs

Use these options to validate your plugin before a real publish.

# Simulate the entire publish process without making changes
# Great for checking authentication and validation rules
elizaos publish --test

# Generate registry submission files locally for inspection
elizaos publish --dry-run

Advanced Publishing

Use these for specific scenarios, like managing a private plugin or handling the registry submission manually.

# Publish to npm but do not open a PR to the registry
elizaos publish --skip-registry

# Test npm-only publishing (skip GitHub and registry)
elizaos publish --test --npm

Development Lifecycle

A typical journey from creation to publishing:

1. Create & Develop

# Create a new plugin from the template
elizaos create -t plugin my-awesome-plugin
cd my-awesome-plugin

# Install dependencies and start development
bun install
elizaos dev

2. Test & Validate

# Run your plugin's tests
elizaos test

# Simulate publish to catch issues early
elizaos publish --test

3. Publish

# Ensure you're logged into npm
bunx npm login

# Publish your plugin
elizaos publish

Process Steps

When you run elizaos publish, the CLI performs these actions:

Validation: Checks CLI version, plugin structure, and package.json
Authentication: Prompts for npm and GitHub credentials if needed
Build: Compiles TypeScript by running bun run build
Publish Package: Pushes to npm
Create GitHub Repo: Creates public repository (if it doesn’t exist)
Submit to Registry: Opens a Pull Request for discovery

Post-Publishing Updates

The elizaos publish command is for initial release only. Use standard tools for updates.

For subsequent updates:

# Bump version in package.json
bun version patch  # or minor/major

# Push new version to npm
bun publish

# Push code and tags to GitHub
git push && git push --tags

The elizaOS registry automatically detects new npm versions.

Authentication

npm Authentication

You must be logged in to npm:

bunx npm login

GitHub Authentication

A Personal Access Token (PAT) is required. You can either:

Set environment variable: export GITHUB_TOKEN=your_pat_here
Enter when prompted by the CLI

Required PAT scopes: repo, read:org, workflow

Plugin Structure

The CLI validates these requirements before publishing:

Requirement	Description	Fix
Plugin Name	Must start with `plugin-`	Auto-checked
Images Directory	Must have `images/` directory	Auto-created
Logo Image	`images/logo.jpg` (400x400px, max 500KB)	Manual
Banner Image	`images/banner.jpg` (1280x640px, max 1MB)	Manual
Description	Meaningful description	Prompted
Repository URL	Format: `github:username/repo`	Auto-fixed
agentConfig	Required in package.json	Auto-fixed

Sample package.json

{
  "name": "plugin-example",
  "version": "1.0.0",
          "description": "An example elizaOS plugin that demonstrates best practices",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "author": "Your Name <[email protected]>",
  "license": "MIT",
  "repository": "github:yourusername/plugin-example",
  "keywords": ["elizaos-plugin", "eliza-plugin"],
  "scripts": {
    "build": "tsc",
    "test": "vitest",
    "dev": "tsc --watch"
  },
  "dependencies": {
    "@elizaos/core": "^1.0.0"
  },
  "devDependencies": {
    "typescript": "^5.0.0",
    "vitest": "^1.0.0"
  },
  "agentConfig": {
    "actions": ["exampleAction"],
    "providers": ["exampleProvider"],
    "evaluators": ["exampleEvaluator"],
    "models": ["gpt-4", "gpt-3.5-turbo"],
    "services": ["discord", "telegram"]
  }
}

The agentConfig section tells elizaOS agents how to load your plugin.

Authentication Errors

# Refresh credentials
bunx npm logout
bunx npm login

GitHub Token Issues

Generate a new PAT with repo, read:org, and workflow scopes:

# Set token
export GITHUB_TOKEN=your_new_token

# Or enter when prompted
elizaos publish

Validation Failures

Use --test to identify issues:

elizaos publish --test

Common problems:

Plugin name doesn’t start with plugin-
Missing or incorrectly sized images
Invalid repository URL format

Build Failures

Debug TypeScript errors:

# Ensure dependencies are installed
bun install

# Run build manually
bun run build

Version Conflicts

Cannot publish over existing versions:

# Check current version
bunx npm view your-plugin version

# Bump version
bun version patch

# Retry
elizaos publish

GitHub Repository Exists

If repository already exists:

# Verify it's correct
gh repo view yourusername/plugin-name

# Publish to npm only (skip GitHub and registry)
elizaos publish --npm

Registry Submission Issues

# Test registry generation
elizaos publish --dry-run

# Check generated files
ls packages/registry/

# Skip registry if needed
elizaos publish --skip-registry

CI/CD Integration

Example GitHub Actions workflow:

name: Publish
on:
  release:
    types: [created]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: oven-sh/setup-bun@v1
      
      - name: Install dependencies
        run: bun install
      
      - name: Build
        run: bun run build
      
      - name: Test
        run: bun test
      
      - name: Publish to npm
        run: bun publish
        env:
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

create: Create a new plugin
plugins: Manage plugins
test: Test before publishing
Publish a Plugin: Complete walkthrough

Getting Started

Commands

What It Does

Usage

Options

Standard Publishing

Testing and Dry Runs

Advanced Publishing

Development Lifecycle

1. Create & Develop

2. Test & Validate

3. Publish

Process Steps

Post-Publishing Updates

Authentication

npm Authentication

GitHub Authentication

Plugin Structure

Sample package.json

Authentication Errors

GitHub Token Issues

Validation Failures

Build Failures

Version Conflicts

GitHub Repository Exists

Registry Submission Issues

CI/CD Integration

Getting Started

Commands

​What It Does

​Usage

​Options

​Standard Publishing

​Testing and Dry Runs

​Advanced Publishing

​Development Lifecycle

​1. Create & Develop

​2. Test & Validate

​3. Publish

​Process Steps

​Post-Publishing Updates

​Authentication

​npm Authentication

​GitHub Authentication

​Plugin Structure

​Sample package.json

​Authentication Errors

​npm Login Issues

​GitHub Token Issues

​Validation Failures

​Build Failures

​Version Conflicts

​GitHub Repository Exists

​Registry Submission Issues

​CI/CD Integration

​Related Commands

What It Does

Usage

Options

Standard Publishing

Testing and Dry Runs

Advanced Publishing

Development Lifecycle

1. Create & Develop

2. Test & Validate

3. Publish

Process Steps

Post-Publishing Updates

Authentication

npm Authentication

GitHub Authentication

Plugin Structure

Sample package.json

Authentication Errors

npm Login Issues

GitHub Token Issues

Validation Failures

Build Failures

Version Conflicts

GitHub Repository Exists

Registry Submission Issues

CI/CD Integration

Related Commands