Video Tutorial: Create + Publish Your Own Plugin
This guide assumes you have a working plugin. If you need to create one first, see Create a Plugin
Once you’ve built and tested your plugin locally, you’ll want to publish it so others can discover and use it. You’ll need an npm account and GitHub account for authentication.

​
Step 1: Prepare for Publishing

Start from your working plugin directory. If you followed the Create a Plugin guide:
Terminal
cd plugin-fal-ai

​
Verify plugin requirements

Your plugin needs these key elements for registry acceptance: Required files: 
plugin-fal-ai/
├── src/
│   └── index.ts         # Your plugin code
├── images/              # Registry assets 
│   ├── logo.jpg        # 400x400px, max 500KB
│   └── banner.jpg      # 1280x640px, max 1MB  
├── package.json         # Plugin metadata
├── README.md           # Documentation
└── dist/               # Built files (from `bun run build`)
What the publish command validates:
  • name starts with plugin- (auto-added by CLI if missing)
  • Custom description (not the default generated placeholder)
  • Required images in images/ directory
1

Add required images

Create an images/ directory if it doesn’t exist:
Terminal
mkdir -p images
Add these two custom images for your plugin’s branding on the registry:
  • logo.jpg - 400x400px square logo (max 500KB)
  • banner.jpg - 1280x640px banner (max 1MB)
Use high-quality images that represent your plugin’s functionality clearly. The logo will appear in plugin listings at various sizes.
2

Update package.json description

Replace the default generated description with something descriptive:
package.json
{
  "name": "plugin-fal-ai",
  "version": "1.0.0",
  "description": "ElizaOS plugin for fal-ai", 
  "description": "Generate videos from text using fal.ai MiniMax Hailuo-02 model", 
  "keywords": ["plugin", "elizaos"]
}
3

Build your plugin

Ensure your plugin is built and ready:
Terminal
bun run build
This creates the dist/ folder that npm will publish.

​
Step 2: Check authentication

Make sure you’re logged into both npm and GitHub:

​
Check npm login

1

Check current npm login

Terminal
npm whoami
If you see your username, you’re already logged in. If you see an error, continue to the next step.
2

Login to npm (if needed)

Terminal
npm login
Follow the prompts to enter your:
  • Username
  • Password
  • Email address
  • One-time password (if 2FA is enabled)

​
Check GitHub authentication

Terminal
gh auth status
If you see your GitHub username, you’re logged in. If you see an error or “not logged in”:
Terminal
gh auth login
If gh command is not found, you’ll need to install GitHub CLI from cli.github.com or the publish command will prompt you to create a token manually.

​
Step 3: Test Publishing (Dry Run)

Before actually publishing, test the entire process to catch any issues.

​
Run publish test

Terminal
elizaos publish --test
This command will:
  • Check your npm and GitHub authentication
  • Validate your plugin structure
  • Check for required images and descriptions
  • Show you exactly what would happen without making any changes
Example output: 
✓ Found existing NPM login: your-username
✓ GitHub token validated
⚠ Plugin validation warnings:
  - Missing required logo.jpg in images/ directory (400x400px, max 500KB)
  - Missing required banner.jpg in images/ directory (1280x640px, max 1MB)
  - Description appears to be default generated description
Your plugin may get rejected if you submit without addressing these issues.
Do you wish to continue anyway? No
Address any validation errors before proceeding. Your plugin may be rejected by maintainers if it’s missing required assets or has placeholder content.

​
Run dry run (optional)

For an even more detailed preview:
Terminal
elizaos publish --dry-run
This generates all the registry files locally in packages/registry/ so you can see exactly what will be submitted.

​
Step 4: Publish Your Plugin

Once your test passes and you’re satisfied with the setup, run the actual publish command.

​
Execute full publish

Terminal
elizaos publish
You will be asked for a scoped Github token and given these instructions:
1

Create GitHub Personal Access Token (when prompted)

  1. Go to GitHub Settings → Developer settings → Personal access tokens
  2. Click “Generate new token (classic)”
  3. Name it “elizaOS Publishing”
  4. Select these scopes:
    • repo (Full control of private repositories)
    • read:org (Read organization membership)
    • workflow (Update GitHub Action workflows)
  5. Click “Generate token”
  6. Copy the token and paste it when prompted by the CLI
GitHub token scope selection showing repo, read:org, and workflow checked
Make sure to test that your plugin is configured correctly before publishing, as it will cause unnecessary delay if something is wrong.
Example successful output: 
✓ Successfully published plugin-fal-ai@1.0.0 to npm
✓ Created GitHub repository: yourusername/plugin-fal-ai
✓ Registry pull request created: https://github.com/elizaos-plugins/registry/pull/123

Your plugin is now available at:
NPM: https://www.npmjs.com/package/plugin-fal-ai
GitHub: https://github.com/yourusername/plugin-fal-ai

​
Step 5: Registry Review Process

​
What happens next

  1. npm Package - Available immediately at https://npmjs.com/package/your-plugin-name
  2. GitHub Repo - Created immediately at https://github.com/yourusername/plugin-name
  3. Registry Pull Request - Opened at elizaos-plugins/registry

​
Registry approval

An elizaOS core team member will review your registry pull request to ensure all requirements are met, the plugin is free of malicious code, and it functions as intended with proper images and a quality description. Typical review time: 1-3 business days If approved: Your plugin appears in the official registry and can be discovered via elizaos plugins list If changes requested: Address the feedback and update your plugin, then re-submit.

​
Step 6: Post-Publishing

​
Plugin is now live!

Once approved, users can install your plugin to their projects:
Terminal
elizaos plugins add plugin-fal-ai

​
Future updates

For plugin updates after initial publishing:
Terminal
# 1. Make your changes and test locally
# 2. Update version in package.json
npm version patch  # or minor/major

# 3. Build and test  
bun run build
elizaos test

# 4. Publish to npm
npm publish

# 5. Push to GitHub
git add .
git commit -m "Update to version x.y.z"
git push origin main
The elizaOS registry automatically syncs with npm updates, so you don’t need to manually update the registry.

​
What’s Next?

Contribute to Core

Help improve elizaOS by contributing to the core framework

Plugin Registry

Explore existing plugins and find inspiration

CLI Reference

Master all elizaOS CLI commands for development

Join Discord Community

Share your plugin and get help from the community