WPForge 🛠️

A cross-platform CLI tool for generating WordPress plugins from WordPress Plugin Boilerplate

🇮🇷 راهنمای فارسی · ⬇️ Download · 📦 Releases · ⚙️ Actions

📖 About

WPForge is a cross-platform command-line tool for quickly generating WordPress plugins using the structure of the WordPress Plugin Boilerplate (WPPB).

It is designed to make starting a new WordPress plugin faster and easier by automatically creating the plugin structure and replacing common boilerplate information such as:

Plugin name
Plugin slug
Plugin URL
Author information
Author email
Author URL
Plugin description

WPForge is written in Python and provides pre-built executables for:

🪟 Windows
🐧 Linux
🍎 macOS

Python does not need to be installed when using the pre-built releases.

✨ Features

🛠️ Generate WordPress plugins from WordPress Plugin Boilerplate
🪟 Windows support
🐧 Linux support
🍎 macOS support
⚡ Interactive CLI
🤖 Non-interactive CLI mode
📝 Automatic plugin metadata replacement
🔤 Automatic plugin slug conversion
📁 Automatic template file and directory renaming
👤 Author configuration support
🌐 Cross-platform configuration file
📦 Standalone executables
🔧 Works with the WordPress CLI (wp)
🚀 No Python installation required for pre-built releases
🔄 Available for multiple operating systems and architectures

📥 Download

Latest Release

🪟 Windows

Download the latest Windows executable and run it from PowerShell or Command Prompt.

For example:

C:\Tools\WPForge\wpforge.exe

You should see:

WPForge - WordPress Plugin Generator

Optional — Add WPForge to PATH

If you want to run:

wpforge

from any directory, add the WPForge directory to your Windows PATH.

After adding it, restart PowerShell or Command Prompt.

Then run:

wpforge --version

🐧 Linux

1. Download WPForge

Open the latest release and download the Linux binary.

For example:

wpforge-linux-x64

2. Make it executable

Open Terminal:

chmod +x wpforge-linux-x64

3. Run it

./wpforge-linux-x64

Optional — Install globally

You can move the executable to a directory in your PATH:

sudo mv wpforge-linux-x64 /usr/local/bin/wpforge

Then:

wpforge --version

You can now run WPForge from any directory.

🍎 macOS

1. Download WPForge

Open the latest release and download the macOS build matching your Mac.

Available builds may include:

Apple Silicon (ARM64)
Intel (x64)

2. Make the binary executable

Open Terminal:

chmod +x wpforge-macos-arm64

3. Run WPForge

./wpforge-macos-arm64

Optional — Install globally

sudo mv wpforge-macos-arm64 /usr/local/bin/wpforge

Then:

wpforge --version

🐍 Python Installation

If you prefer running WPForge directly from source, Python is required.

Requirements

Python 3.10+
pip

Clone the repository

git clone https://github.com/alirezasayadi/WPForge.git

Enter the directory:

cd WPForge

Create a virtual environment

Windows

python -m venv .venv

Activate it:

.venv\Scripts\activate

Linux / macOS

python3 -m venv .venv

Activate it:

source .venv/bin/activate

Install dependencies

pip install -r requirements.txt

Run WPForge

python main.py

🚀 Usage

WPForge supports both:

Interactive mode
Non-interactive mode

🧑‍💻 Interactive Mode

Interactive mode is recommended for beginners.

Simply run:

wpforge

or:

wpforge new

WPForge will ask you for the required information.

Example

Plugin name: My Awesome Plugin
Plugin slug: my-awesome-plugin
Plugin URL: https://example.com/my-plugin
Author name: John Doe
Author email: john@example.com
Author URL: https://example.com
Plugin description: My awesome WordPress plugin

After entering the information, WPForge generates the plugin automatically.

📁 Where Is the Plugin Created?

WPForge creates the plugin inside the current directory.

For example:

wordpress/
└── wp-content/
    └── plugins/
        └── my-awesome-plugin/

If you run:

cd /path/to/wordpress/wp-content/plugins

then:

wpforge new

will create:

wp-content/
└── plugins/
    └── my-awesome-plugin/

WPForge also checks whether the current directory looks like:

wp-content/plugins

If it does not, WPForge displays a warning.

⚙️ Non-Interactive Mode

Non-interactive mode is useful for:

Scripts
Automation
CI/CD
GitHub Actions
Developers who already know the required values

Use:

wpforge new --non-interactive \
  --plugin-name "My Plugin" \
  --plugin-slug my-plugin \
  --plugin-url https://example.com/my-plugin \
  --author-name "John Doe" \
  --author-email john@example.com \
  --author-url https://example.com \
  --plugin-description "My WordPress plugin"

Windows PowerShell

Use backticks:

wpforge new --non-interactive `
  --plugin-name "My Plugin" `
  --plugin-slug my-plugin `
  --plugin-url https://example.com/my-plugin `
  --author-name "John Doe" `
  --author-email john@example.com `
  --author-url https://example.com `
  --plugin-description "My WordPress plugin"

Or simply use one line:

wpforge new --non-interactive --plugin-name "My Plugin" --plugin-slug my-plugin --plugin-url https://example.com/my-plugin --author-name "John Doe" --author-email john@example.com --author-url https://example.com --plugin-description "My WordPress plugin"

📋 Command Options

Run:

wpforge new --help

Available options:

Option	Description
`--plugin-name`	Plugin name
`--plugin-slug`	Plugin slug
`--plugin-url`	Plugin URL
`--author-name`	Author name
`--author-email`	Author email
`--author-url`	Author URL
`--plugin-description`	Plugin description
`--non-interactive`	Disable interactive prompts

🔤 Plugin Slug

The plugin slug must contain:

Lowercase letters
Numbers
Hyphens

Valid

my-plugin
woocommerce-tools
plugin123
my-plugin-123
advanced-discount

Invalid

My Plugin
my_plugin
My-Plugin
-my-plugin
my--plugin

The slug is also used to generate PHP naming conventions.

For example:

my-awesome-plugin

becomes:

my_awesome_plugin

and:

MyAwesomePlugin

👤 Configuration

WPForge supports a configuration file named:

.wpforge

The file is stored in the user's home directory.

Windows

Usually:

C:\Users\YourName\.wpforge

Linux / macOS

Usually:

~/.wpforge

Configuration Example

Create:

.wpforge

with:

author=John Doe
authorEmail=john@example.com
authorUrl=https://example.com

WPForge will automatically use these values as defaults.

This is especially useful if you create plugins frequently.

🧪 Example

Suppose you run:

wpforge new

and enter:

Plugin name: Advanced Security
Plugin slug: advanced-security
Plugin URL: https://example.com/advanced-security
Author name: John Doe
Author email: john@example.com
Author URL: https://example.com
Plugin description: Advanced security tools for WordPress.

WPForge creates:

advanced-security/

with the WordPress Plugin Boilerplate structure.

The generated files are automatically updated with the provided information.

🔧 WordPress CLI

After generating the plugin, you can activate it using WP-CLI:

wp plugin activate my-plugin

For example:

wp plugin activate advanced-security

Make sure WP-CLI is installed and you are running the command from your WordPress installation.

📦 Releases

WPForge releases are published on GitHub.

View all releases

Each release may contain builds for:

🪟 Windows
🐧 Linux
🍎 macOS
🐍 Python/source

Recommended Version

For most users, download the latest stable release.

You do not need to download the source code unless you want to develop WPForge itself.

🚀 Creating a Release

WPForge uses Git tags to create new releases.

When a new version tag such as v1.0.0 is pushed to GitHub, GitHub Actions automatically:

🪟 Builds Windows x64
🐧 Builds Linux x64
🍎 Builds macOS ARM64
🍎 Builds macOS Intel x64
🔐 Generates SHA-256 checksums
📦 Creates a GitHub Release
⬆️ Uploads all compiled binaries to the release
📝 Generates release notes

You do not need to manually build the application for each operating system.

📋 Release Requirements

Before creating a release, make sure:

Your working tree is clean.
All changes have been committed.
You are on the correct branch.
The project builds successfully.
The version number is correct.

Check your Git status:

git status

You should ideally see:

nothing to commit, working tree clean

🪟 Windows

WPForge includes:

scripts/release.bat

This script is intended for Windows users.

1. Open Command Prompt

Open Command Prompt (CMD) and go to the WPForge directory:

cd D:\WPForge

You can also use another directory if WPForge is located elsewhere.

2. Run the release script

For example, to release version 1.0.0:

scripts\release.bat 1.0.0

The script will create and push:

v1.0.0

to GitHub.

3. What happens next?

After the tag is pushed:

release.bat
    ↓
Git commit
    ↓
Git tag v1.0.0
    ↓
Push tag to GitHub
    ↓
GitHub Actions starts
    ↓
Build Windows
Build Linux
Build macOS ARM64
Build macOS x64
    ↓
Generate SHA256SUMS.txt
    ↓
Create GitHub Release
    ↓
Upload release files

You can monitor the build from:

GitHub → Actions

🐧 Linux / 🍎 macOS

WPForge also includes:

scripts/release.sh

The same script can be used on Linux and macOS.

1. Open Terminal

Go to the WPForge directory:

cd /path/to/WPForge

For example:

cd ~/WPForge

2. Make the script executable

You only need to do this once:

chmod +x scripts/release.sh

3. Create a release

For example:

./scripts/release.sh 1.0.0

This creates:

v1.0.0

and pushes the tag to GitHub.

GitHub Actions will then automatically build all supported platforms.

🔢 Versioning

WPForge releases use the following format:

MAJOR.MINOR.PATCH

For example:

1.0.0
1.0.1
1.1.0
2.0.0

The Git tag automatically receives the v prefix:

v1.0.0
v1.0.1
v1.1.0
v2.0.0

Version examples

Bug fix:

1.0.0 → 1.0.1

New backward-compatible feature:

1.0.0 → 1.1.0

Breaking change:

1.0.0 → 2.0.0

⚠️ Important

Do not manually create the GitHub Release when using the release scripts.

The release process is automated.

You only need to create and push the version tag.

GitHub Actions will create the Release automatically.

🛠️ Manual Release

If you do not want to use the provided scripts, you can create a release manually.

First commit your changes:

git add .
git commit -m "Release v1.0.0"

Create the tag:

git tag v1.0.0

Push the branch:

git push origin main

Push the tag:

git push origin v1.0.0

After the tag is pushed, GitHub Actions automatically starts the release workflow.

🔍 Checking the Release

After pushing the tag, open the GitHub repository and go to:

Actions

You should see:

Build and Release WPForge

Wait until all jobs finish successfully.

The workflow should produce:

Windows x64
Linux x64
macOS ARM64
macOS Intel x64
SHA256SUMS.txt

The final files will be available under:

GitHub
  → Releases
    → WPForge v1.0.0

📦 Release Files

A typical WPForge release contains:

WPForge-v1.0.0-Windows-x64.exe
WPForge-v1.0.0-Linux-x64
WPForge-v1.0.0-macOS-arm64
WPForge-v1.0.0-macOS-x64
SHA256SUMS.txt

Windows

Download:

WPForge-v1.0.0-Windows-x64.exe

No Python installation is required.

Linux

Download:

WPForge-v1.0.0-Linux-x64

Then:

chmod +x WPForge-v1.0.0-Linux-x64

Run:

./WPForge-v1.0.0-Linux-x64

macOS Apple Silicon

For Apple Silicon Macs such as M1, M2, M3 and M4:

WPForge-v1.0.0-macOS-arm64

Run:

chmod +x WPForge-v1.0.0-macOS-arm64
./WPForge-v1.0.0-macOS-arm64

macOS Intel

For Intel-based Macs:

WPForge-v1.0.0-macOS-x64

Run:

chmod +x WPForge-v1.0.0-macOS-x64
./WPForge-v1.0.0-macOS-x64

🔐 SHA-256 Checksums

Every release includes:

SHA256SUMS.txt

This file contains SHA-256 hashes for the release binaries.

You can use it to verify that a downloaded file has not been corrupted or modified.

Windows

PowerShell:

Get-FileHash .\WPForge-v1.0.0-Windows-x64.exe -Algorithm SHA256

Linux

sha256sum WPForge-v1.0.0-Linux-x64

macOS

shasum -a 256 WPForge-v1.0.0-macOS-arm64

Compare the generated hash with the corresponding value in:

SHA256SUMS.txt

❌ If a Release Fails

If GitHub Actions fails:

Open the repository on GitHub.
Go to Actions.
Open the failed workflow.
Select the failed job.
Check the error message.

Do not immediately create another tag with the same version.

For example, if:

v1.0.0

failed, fix the problem first.

Then use a new patch version:

v1.0.1

unless the original tag can safely be deleted and recreated.

💡 Recommended Release Workflow

For normal development, the recommended workflow is:

1. Make changes
      ↓
2. Test locally
      ↓
3. Commit changes
      ↓
4. Run release.bat / release.sh
      ↓
5. Tag vX.Y.Z is pushed
      ↓
6. GitHub Actions builds all platforms
      ↓
7. GitHub Release is created
      ↓
8. Users download the binaries

This keeps the release process simple and consistent across Windows, Linux and macOS.

🔄 Updating WPForge

Windows

Download the new Windows release and replace the old executable.

Linux

Download the latest binary and replace the existing installation:

sudo mv wpforge-linux-x64 /usr/local/bin/wpforge

macOS

Download the latest macOS binary and replace the previous version.

Python

If running from source:

git pull

Then update dependencies:

pip install -r requirements.txt --upgrade

🛠️ Development

Clone the repository:

git clone https://github.com/alirezasayadi/WPForge.git

Enter the project:

cd WPForge

Create a virtual environment.

Windows

python -m venv .venv
.venv\Scripts\activate

Linux / macOS

python3 -m venv .venv
source .venv/bin/activate

Install dependencies:

pip install -r requirements.txt

Run:

python main.py

Show help:

python main.py --help

Create a plugin:

python main.py new

🏗️ Building WPForge

WPForge can be packaged as a standalone executable using PyInstaller.

The generated executable does not require Python to be installed on the target machine.

Build instructions may vary depending on the target operating system.

GitHub Actions automatically builds release packages for supported platforms.

🤖 GitHub Actions

WPForge uses GitHub Actions to automate:

Testing
Building
Packaging
Release creation

The project is designed to produce platform-specific builds for:

Windows
Linux
macOS

Release artifacts are attached automatically to GitHub Releases.

🧩 Project Structure

WPForge/
├── main.py
├── requirements.txt
├── README.md
├── LICENSE
├── templates/
│   └── wordpress-plugin/
│       └── plugin-name/
└── .github/
    └── workflows/
        └── release.yml

The templates/wordpress-plugin/plugin-name directory contains the WordPress Plugin Boilerplate template used by WPForge.

📚 Based On

WPForge is inspired by and based on the work of:

Tmeister's WPPB CLI
WordPress Plugin Boilerplate

WPForge provides its own CLI implementation and tooling around the WordPress Plugin Boilerplate structure.

📄 License

WPForge is licensed under the GNU General Public License v2.0 or later (GPL-2.0-or-later).

See:

LICENSE

for the complete license text.

🤝 Contributing

Contributions are welcome.

If you find a bug or have an idea:

Open an issue.
Describe the problem or feature.
Provide reproduction steps when applicable.
Submit a pull request if you have a fix.

🐛 Bug Reports

When reporting a bug, please include:

Operating system
WPForge version
Python version (if running from source)
Command used
Full error message
Steps to reproduce the problem

Example:

OS: Windows 11
WPForge: v1.0.0
Python: 3.12

Command:
wpforge new

Error:
...

⭐ Support the Project

If WPForge is useful to you:

⭐ Star the repository on GitHub.

You can also report bugs, suggest features, and contribute code.

Made with ❤️ by Alireza Sayadi

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
templates/wordpress-plugin/plugin-name		templates/wordpress-plugin/plugin-name
tests		tests
.gitattributes		.gitattributes
.gitignore		.gitignore
LICENSE		LICENSE
README.fa.md		README.fa.md
README.md		README.md
main.py		main.py
release.bat		release.bat
release.sh		release.sh
requirements.txt		requirements.txt

Latest commit

History

Folders and files

Repository files navigation

WPForge 🛠️

📖 About

✨ Features

📥 Download

🪟 Windows

Optional — Add WPForge to PATH

🐧 Linux

1. Download WPForge

2. Make it executable

3. Run it

Optional — Install globally

🍎 macOS

1. Download WPForge

2. Make the binary executable

3. Run WPForge

Optional — Install globally

🐍 Python Installation

Requirements

Clone the repository

Create a virtual environment

Windows

Linux / macOS

Install dependencies

Run WPForge

🚀 Usage

🧑‍💻 Interactive Mode

Example

📁 Where Is the Plugin Created?

⚙️ Non-Interactive Mode

Windows PowerShell

📋 Command Options

🔤 Plugin Slug

Valid

Invalid

👤 Configuration

Windows

Linux / macOS

Configuration Example

🧪 Example

🔧 WordPress CLI

📦 Releases

Recommended Version

🚀 Creating a Release

📋 Release Requirements

🪟 Windows

1. Open Command Prompt

2. Run the release script

3. What happens next?

🐧 Linux / 🍎 macOS

1. Open Terminal

2. Make the script executable

3. Create a release

🔢 Versioning

Version examples

⚠️ Important

🛠️ Manual Release

🔍 Checking the Release

📦 Release Files

Windows

Linux

macOS Apple Silicon

macOS Intel

🔐 SHA-256 Checksums

Windows

Linux

macOS

❌ If a Release Fails

💡 Recommended Release Workflow

🔄 Updating WPForge

Windows

Linux

macOS

Python

🛠️ Development

Windows

Linux / macOS