
wordpress-cli
dev.wirecat/wordpress-cli
wordpress for agents over MCP. Set up a profile with the wordpress CLI first.
Documentation
wordpress: WordPress CLI and MCP server for AI agents
Write and check your blog without opening wp-admin. Ask Claude, ChatGPT, Codex or any AI agent, and it answers from a copy of your WordPress posts and pages on your computer, and writes drafts for you to publish.
Docs · Install · Usage · Discord
- Ask instead of clicking. "Which drafts did I start this month?" gets an answer in a second, in Claude Code, Codex, Claude Desktop or any app that speaks MCP.
- Your site, offline. Posts and pages with every status, the trash too, are kept on your computer as Markdown.
- Drafts from your agent, publishing on your word. The agent writes a draft. Publishing is a step of its own, with its own permission.
What you get
- The answer, not the search. Ask about a post in your own words. The agent finds it by its title and text, with its status, tags and author.
- Every draft and scheduled post in one list. Filter by status, by tag, by author or by the day it went out.
- Drafts written for you. Hand the agent your notes, and it makes a draft with a title, an excerpt and tags.
- Publish now or later. Publish a draft at once, or schedule it for a time you name. Take a post back to a draft with one command.
- The whole WordPress API too. Media, comments, menus and the rest of the site, one command per operation.
You: Which drafts do I have about pricing?
Agent: (runs wordpress blog posts search pricing, then posts list status:draft)
· 41 "Why we changed our pricing", draft, last changed on Monday
· 57 "Pricing FAQ", draft, tags: pricing, faq
You: Turn my notes in pricing-notes.md into a third draft.
Agent: (runs wordpress blog posts create --title "Pricing in 2027" --text-file pricing-notes.md)
Draft 63 is ready. Publish it when you want.
Invented posts, illustrative output.
Why wordpress
- A copy of your site on your computer.
synccopies your posts and pages, tags, categories and authors into a local store. Lists and search answer from it with no request to your site, also offline. - A permission on every action. Creating, changing, publishing and deleting each have their own key, and each
asks first at a terminal.
WCWP_READ_ONLY=1stops every write. - The password stays in your system keyring. It never appears in output, errors or run records, and is never taken as an argument.
- Your posts beside your other context. They sit in the same local store as your messages, mail, notes and meetings from the other WireCat tools.
- Safe edits. A write checks that the post did not change on the site since the last sync. A post with galleries or embeds keeps its body unless you say to replace it.
- Free and open source. Apache 2.0.
Quick start
npm install -g @wirecat/wordpress-cli
wordpress skill install # the agent skill, for Claude Code, Codex, Gemini CLI and OpenClaw
wordpress blog session start --site blog.example.com --login anna # paste your application password
wordpress blog sync # copy your posts, pages, tags and authors
wordpress blog posts list status:draft
blog is a profile, a name you choose for one site and one WordPress user. It is the first word of every command
that uses an account, and none is ever assumed.
The application password. In WordPress, open Users → Profile, find Application Passwords, give the new password
a name and click Add. WordPress 5.7 or later makes it, and only over https. session start asks for it without
showing it, checks it with your site and keeps it with that site in the system keyring. The password goes to that
site alone, never to another site on the same host. For a full copy, sign in as an Administrator.
The command is wordpress, not wp: the official WP-CLI already uses wp. You need Node.js 22.16 or a later 22.x,
or Node.js 24 or later. wordpress doctor needs no network and shows what is set up.
More: installation and sign-in, step by step
Use it with your agent
Ask in plain words. The agent picks the commands.
"Use wordpress. What did I publish last month, and what is still a draft?" "Use wordpress. Write a draft from notes.md and tag it release." "Use wordpress. Schedule draft 63 for Monday 9:00."
- Claude Code, Codex, Gemini CLI and other agents with a terminal run
wordpressthemselves.wordpress skill installteaches them how. - Claude Desktop, Cursor and other MCP apps connect to the WordPress MCP server,
wordpress blog mcp serve. - ChatGPT or Claude in the browser reach it through your own tunnel, after a login with a one-time code.
wordpress blog config set permissions.posts.publish deny # an agent writes drafts, you publish
wordpress blog mcp add claude-code --allow-writes # or: codex
wordpress blog mcp config # the entry for Claude Desktop, Cursor and others
Over MCP nobody is at a terminal to answer a question, so a write set to ask goes ahead. An agent over MCP can
publish a post. That is the owner's choice for this tool. wordpress blog runs list shows each publication for 7
days (keep_successful_runs_for_days). The first line above stops it.
More: agents and MCP · permissions
What needs which key
- Publishing needs
<route>.publish(posts.publish,pages.publish): a write that setsstatustopublishorfuture, or that setsdate,date_gmtorpassword, unless the same call setsstatustodraft,pendingorprivate. WordPress publishes a scheduled post whose date moves into the past, and a password taken off a published post makes it public, with no status in the call.privateis not public. Where a route'sstatusstarts atpublish(menu items, for one), each create needs the key, as the write publishes unless it says otherwise. - Deleting needs
<route>.delete. Withforce=true, which deletes for good instead of moving to the trash, it needs<route>.delete.forcetoo. Both ask by default. - WordPress's batch route (
batch/v1) is never offered: one batch call would run other routes' writes past their keys.
Known limit of the raw api group: WordPress publishes a scheduled post whose time has already passed (a
missed schedule) on any edit, a title change too. The CLI cannot see that without reading the post first.
What it can do
Read your posts
wordpress blog posts list status:published "published:>=2026-10-01"
wordpress blog posts list type:page
wordpress blog posts search "pricing change"
wordpress blog posts show 41 # the text as Markdown, its tags and authors by name
wordpress blog tags list # tags and categories with their ids
wordpress blog users list # the authors
Write and publish
wordpress blog posts create --title "Version 3" --text-file notes.md --tags 12,14
wordpress blog posts update 63 --description "What changed in version 3"
wordpress blog posts publish 63 # now
wordpress blog posts publish 63 --at-time 2026-12-01T09:00:00Z # later
wordpress blog posts unpublish 63 # back to a draft
wordpress blog posts delete 63 # to the trash
Any WordPress API operation
wordpress blog api list # every operation, without calling WordPress
wordpress blog api media-list # the media library
More: using wordpress · every command
How it works
- An application password. You make it in your WordPress profile. It can do what your user can, no more. It is
kept in the system keyring, or in a private file with
--credential-storage file. - A local copy.
synccopies posts and pages with every status, the trash included, with their tags, categories and authors, into the WireCat local store. Text is kept as Markdown. Later syncs read only what changed. - Writes go to your site.
posts createmakes a draft, and the other writes change the post on your site, then the copy. - Made for scripts.
--jsonprints one JSON value for every command, and an error comes as JSON with a code to branch on.
Settings and permissions
Each profile has a level for every command and every WordPress API operation: allow, ask, readonly or deny.
Every posts write asks first at a terminal.
wordpress blog config set permissions.posts.publish deny # nothing goes public from this profile
wordpress blog config show # each setting and where it came from
More: permissions · settings
Limits
- Only self-hosted WordPress with application passwords. WordPress.com sites, which sign in with OAuth, are not supported. Sign-in through the browser is not there yet: you paste the password.
- An Author or Contributor gets only their own posts, and no pages: WordPress refuses the pages list to both, and the sync says so. A Contributor gets only their drafts and posts waiting for review. For both, a post that leaves their view stays in the copy as it was: one deleted for good, or a Contributor's post an editor published. Only an Administrator gets the users list. Sign in as an Administrator for a full copy.
- No view counts. WordPress itself keeps none, and Jetpack stats are not supported.
- A post with galleries, columns, embeds or iframes keeps its body:
posts updatechanges its title, excerpt, tags and status only, unless you add--replace-body. - Plugin fields, such as those of SEO or custom field plugins, are not in the API description. The
apigroup sends them only in a raw--body. - Before 1.0, a minor version may change commands,
--jsonfields and MCP tools. The changelog lists each such change under "may break callers".
Security
The application password can do what your WordPress user can, so wordpress keeps it in the system keyring and
never prints it, in output, errors or run records. It talks only to the site you signed in to. Text from WordPress is
marked as untrusted, so an agent reads a post as data, not as an instruction.
More: security · Report a vulnerability: SECURITY.md
When something goes wrong
wordpress doctor # what is set up, without connecting
wordpress blog session status --check # asks your site whose password it is
More: troubleshooting · Ask on Discord · Bugs go to this repository's issues.
Documentation
Everything is in docs/: installation, usage, MCP, permissions, settings, the command reference and the roadmap.
Development
You need Node.js 22.16 or a later 22.x, or Node.js 24 or later, and pnpm.
pnpm install && pnpm test
Tests use a fake WordPress built from the API description of WordPress 6.9.4, with invented posts, and nothing
reaches a real site. The CLI is described in one file, wirecat.config.ts, and started from
cli-template.
More: design · working rules
Pull requests, bug reports and ideas go to issues.
Part of WireCat
wordpress is one of the WireCat tools: open-source, local-first command-line tools that give
AI agents your context from messengers, mail, calendars, CRMs and documents. Each one works on its own.
License
@wirecat/wordpress-clinpm install @wirecat/wordpress-cli