Publishing a plugin to the WordPress.org directory has a reputation for being fiddly — and that reputation is earned. You have to zip your files in exactly the right shape, hand-check a readme.txt against rules you can’t see, install developer tools to run the official “Plugin Check,” fill in a web form, and — once you’re approved — wrestle with SVN, a version-control system.
Pressship collapses all of that into a handful of plain commands. It’s an open-source tool from Automattic that validates, packages, submits, and releases your plugin from the terminal. If you’ve ever run npm publish, it’ll feel familiar. If you haven’t, don’t worry — this guide assumes nothing and walks you through every step.
By the end you’ll have your plugin submitted to WordPress.org for review. I’ll point out the exact spots where things commonly go wrong, because I hit a few of them publishing a real plugin and they’re easy to sidestep once you know they’re there.
Why this is so much easier than the old way
Here’s what you’d normally juggle by hand, and what Pressship does for you instead.
It checks everything before you upload. WordPress.org reviewers run your plugin through a tool called Plugin Check, and they reject plugins for common mistakes (unescaped output, missing security checks, a malformed readme). Pressship runs that same Plugin Check and the official readme validator locally, so you find problems on your own machine instead of waiting days for a rejection email.
It sets up the hard stuff automatically. Plugin Check normally needs you to install WordPress, a database, and command-line tools first. Pressship quietly downloads and wires up its own throwaway environment, so you don’t have to install or configure anything.
It packages the zip correctly. WordPress.org is picky about the exact folder structure inside your zip. Pressship builds it the right way every time.
It figures out what you’re trying to do. A single publish command notices whether your plugin is brand new (submit for review), already pending (re-upload), or approved (release). You don’t have to remember which flow you’re in.
It tames SVN. Once your plugin is approved, releasing updates normally means learning Subversion. Pressship handles the checkout, the trunk sync, the version tags, and the commit. If SVN isn’t installed, it offers to install it for you.
The short version: less time on the WordPress.org publishing dance, more time on your actual plugin.
Before you start (the prerequisites)
You’ll need three things:
- Node.js version 20 or newer. This is the runtime that powers Pressship. Check whether you have it by opening Terminal and typing
node --version. If you see a number likev20.xor higher, you’re set. If not, download it from nodejs.org. - A WordPress.org account. This is the free account you use on wordpress.org (not wordpress.com — they’re different). If you don’t have one, register here.
- Your plugin folder, with a main PHP file and a
readme.txt. If your plugin is ready to install and test locally, it’s ready for this.
Techie note: You don’t actually “install” Pressship. Every command below uses
npx, which downloads and runs the latest version on the fly. If you prefer a permanent install, runnpm install -g pressshiponce and then drop thenpxfrom every command. WP-CLI users can instead runwp package install Automattic/pressshipand usewp ship ....
The step-by-step guide
Open the Terminal app (on a Mac, it’s in Applications → Utilities; on Windows, use PowerShell or Windows Terminal). Every command below is typed there and run by pressing Enter.
Step 1 — Go to your plugin folder
Tell the terminal which folder your plugin lives in using the cd (“change directory”) command. Put the path in quotes if it contains spaces:
cd "/path/to/your-plugin"
A quick shortcut on a Mac: type cd (with a space), then drag your plugin’s folder from Finder onto the Terminal window, and the path fills itself in. Press Enter.
Step 2 — Log in to WordPress.org
npx pressship login
This opens a real browser window at the WordPress.org login page. Log in there as you normally would. Pressship watches for a successful login and then saves only the browser session locally — it never sees or stores your password.
Watch out: The very first time, Pressship needs a small browser engine (Chromium) to do this. If it fails with a message like “Could not install Playwright Chromium automatically” or an error mentioning
'./cli' is not defined, don’t panic — it’s a known first-run hiccup. Install the engine manually with one command and then re-run the login:
npx playwright install chromium npx pressship login
If that still complains, clear the cache and reinstall cleanly:
rm -rf ~/.npm/_npxthennpm install -g pressship, and trypressship loginagain.
Confirm it worked:
npx pressship whoami
It should print your WordPress.org username.
Step 3 — Check your plugin for problems
npx pressship verify .
(The . means “the plugin in this folder.”) This runs the official WordPress.org readme validator and Plugin Check — the same checks the review team will run. The first time, it downloads its own mini-WordPress to do this, so give it a minute.
Fix anything it flags before moving on. A clean result looks like “Readme validation: no findings” and Plugin Check reporting “No errors found.”
Don’t be alarmed by this one: Plugin Check may show
1 warningwith[plugin_check.unparsed_output]. Read the line right underneath it — if it says “Success: Checks complete. No errors found,” you’re fine. That “warning” is just Pressship not perfectly parsing one line of output; it is not a problem with your plugin.
Techie note: Plugin Check needs PHP installed. Modern macOS doesn’t ship with PHP, so if
verifycomplains about a missing PHP, runbrew install php(with Homebrew) and try again. Don’t want to install it? You can skip the local Plugin Check by adding--skip-plugin-checkto the submit command in Step 5 — WordPress.org will run it during review regardless. Running it locally just means fewer surprises.
Step 4 — Do a dry run
Before uploading anything, package it up and look at what would be sent — without sending it:
npx pressship publish . --dry-run
Pressship may ask you to “Choose publish target.” For a brand-new plugin, pick “Submit for WordPress.org review.” (You’ll also see a note that SVN isn’t installed — ignore it for now; SVN only matters after you’re approved.)
It then prints the list of files that will go into your zip. This is the most important thing to check. Make sure the files that make your plugin actually work are in the list — your main PHP file, your readme.txt, and any compiled assets — and that junk like .DS_Store is not.
The gotcha that bites everyone: Pressship (sensibly) excludes folders named
build/by default, because for most projects that’s throwaway compiler output. But many modern block-editor plugins ship their real JavaScript and CSS from abuild/folder. If yours does, that folder will be silently left out of the zip — and your published plugin will do nothing at all.
The fix is a one-time file. Create a file named.pressshipignorein your plugin folder and add these lines to force the build folder back in:!build !build/**
> Run the dry run again and confirm your `build/` files now appear in the list.
> **Where do screenshots go?** Not in the plugin zip. WordPress.org listing images (screenshots, icon, banner) belong in a folder named `.wordpress-org/` inside your plugin. Pressship pushes those to the directory automatically when you release, and keeps them out of the file your users download. Name screenshots `screenshot-1.jpg`, `screenshot-2.jpg`, etc., matching the order in your readme's `== Screenshots ==` section — and make sure the file extension matches the real image type (a JPEG saved as `.png` will cause trouble).
### Step 5 — Submit for review
When the dry run looks right, do it for real:
npx pressship publish .
Choose **"Submit for WordPress.org review"** again. Pressship runs the checks one last time, then asks for a short plugin overview for the submission form — it pre-fills this from your plugin's description, and pressing Enter to accept it is usually fine. Then it uploads.
Success looks like a confirmation that your plugin was submitted, with a status of **"Awaiting Review,"** an assigned slug (your future URL — e.g. `wordpress.org/plugins/your-plugin`), and a note that an email is on its way.
### Step 6 — Track the review
npx pressship status your-plugin
This shows the current state — *Awaiting Review*, *In Review*, and so on. WordPress.org will also email you. **Reviews are done by real people and take anywhere from 1 to 10 days** (they aim for 5 business days). If the reviewers ask for changes, make them and simply run `npx pressship publish .` again to re-upload.
> **One small thing to confirm:** the confirmation email goes to whatever address is on your WordPress.org account, which isn't always the one you check most. Make sure you're watching the right inbox, check spam, and consider whitelisting `plugins@wordpress.org`.
---
## After approval: making it live
Getting approved doesn't automatically make your plugin live — there's one final step. Once approved, you get access to WordPress.org's SVN repository, and "releasing" is what actually publishes your code and your screenshots. With Pressship, it's the same command you already know:
npx pressship publish .
Because your plugin now exists in SVN, `publish` automatically switches to the **release** flow. It checks out the repository, copies your files into the right place, creates a version tag, syncs your `.wordpress-org/` images to the listing, and commits — all the SVN gymnastics, handled for you.
The first time you release, it'll ask for a WordPress.org SVN password (a special password, separate from your login). It points you to the page to generate one; you paste it in once, and Pressship remembers it for next time.
> **If SVN isn't installed**, Pressship detects your operating system and offers to install Subversion for you with the right command. Just say yes.
### Shipping updates later
For every future version, it's two commands:
npx pressship version patch # bumps 1.0.0 → 1.0.1 (or use minor / major)
npx pressship publish . # releases it
`version` updates the version number in both your main file and your readme at the same time, so they can never drift out of sync. (Remember to also add a note under `== Changelog ==` in your `readme.txt`.)
---
## Bonus: Pressship Studio
If the terminal isn't your happy place, run:
npx pressship studio
This opens **Studio** — a local, VS Code-style workspace in your browser. You get a file editor, a live preview of your plugin running in a throwaway WordPress (via [WordPress Playground](https://wordpress.org/playground/)), Plugin Check results tied back to the exact files and lines, an AI helper whose changes you explicitly approve or reject, and a release panel showing versions, SVN tags, and package size. It's the same engine as the commands above, with a friendly face on top. Helpfully, it also prints the equivalent terminal command for each action, so it doubles as a way to learn the CLI.
---
## The whole flow at a glance
Step Command What it does Log in `npx pressship login` Browser login, saves your session Check `npx pressship verify .` Runs the readme validator + Plugin Check Preview `npx pressship publish . --dry-run` Packages and shows the file list, no upload Submit `npx pressship publish .` Uploads to the WordPress.org review queue Track `npx pressship status your-plugin` Shows the review status Release `npx pressship publish .` (After approval) publishes live via SVN Update `npx pressship version patch` then `publish .` Bumps the version and releases it
---
## Making it even easier: pairing Pressship with Claude Cowork
Pressship removes most of the friction from publishing. But I went one step further and ran the whole thing alongside **Claude Cowork** — the desktop app where Claude can read the files in a folder you point it at, run commands, and talk you through a process as it happens. The combination turned "publish my plugin" into a guided conversation, and it caught problems I would otherwise have shipped.
Here's what that actually looked like.
**It inspected my plugin and caught the showstopper before I uploaded.** I pointed Cowork at my plugin folder and asked it to get me ready for WordPress.org. It read every file, packaged a test zip in its own sandbox, and immediately noticed that my `build/` folder — the folder holding the JavaScript that makes the plugin *work* — was being excluded. Left unfixed, I'd have published a plugin that did nothing. It created the `.pressshipignore` fix for me and re-packaged to prove it was sorted.
**It cleaned up the small stuff.** It spotted that my screenshots were JPEGs saved with a `.png` extension, moved them into the proper `.wordpress-org/` folder with the right names, bumped my "Tested up to" value to the current WordPress version so the listing wouldn't show an "untested" warning, and removed stray `.DS_Store` files — all the little things reviewers and users notice.
**It handed me the exact commands to run.** Because the actual login and upload have to happen on your own machine (they use your browser and your account), Cowork wrote me a precise, copy-paste runbook: which command to run, in which order, and what a good result looks like at each step.
**It troubleshooted live.** When `pressship login` threw that Playwright Chromium error, I pasted the message straight into the chat and got back the exact two commands to fix it — no searching forums. When Plugin Check showed its scary-looking `1 warning`, Cowork read the output with me and confirmed it was the harmless cosmetic one, so I submitted with confidence instead of second-guessing.
**It set up a watch for me.** After submitting, I asked it to keep an eye on the review. It created a scheduled task that checks each morning whether the plugin has gone live on WordPress.org and pings me the day it does — so I don't have to keep refreshing a dashboard.
The pattern is worth stealing even if your plugin is different from mine: **let Cowork do the inspection, prep, and packaging in its sandbox, then run the browser-and-account steps yourself with the runbook it gives you.** Pressship keeps the publishing flow honest and explicit; Cowork reads your real files, catches the gotchas first, and explains the confusing bits in plain English as they come up. Together they make the whole thing feel less like a process and more like having an experienced co-pilot in the passenger seat.
> **Heads up on the split:** Cowork runs commands in an isolated sandbox, not your actual terminal. That's perfect for reading files, validating, and building test zips — but the steps that log into WordPress.org and upload must run in your own Terminal, because they need your browser session and account. Cowork is upfront about this and gives you the commands to run; you stay in control of anything that touches your account.
---
## Wrapping up
Publishing to WordPress.org used to mean memorizing a checklist of zip structures, validators, and SVN incantations. Pressship turns it into a short, predictable conversation with your terminal: log in, verify, dry run, publish. It catches the mistakes that get plugins rejected *before* you upload, sets up the awkward tooling for you, and uses one smart command for submitting, re-uploading, and releasing.
The two things to remember if you take nothing else away: **always do a **`--dry-run`** first and read the file list** (that's where the `build/` folder surprise hides), and **a clean local Plugin Check is the single best way to get approved faster**. Do those, and the rest really is as easy as it looks.
---
*Pressship is an Automattic-maintained community project and unofficial tooling for WordPress.org publishing workflows — not an official WordPress.org service. Full documentation lives at ****[pressship.org](https://pressship.org/)****, and the source is on ****[GitHub](https://github.com/Automattic/pressship)****. WordPress® is a trademark of the WordPress Foundation.*
Leave a Reply