MCP server
The WordPress CLI
for the AI coding agent era
Builder-native. No SSH. Works on every managed host.
Built on a WordPress-native execution cycle. Extensions and callbacks arrive in v0.2.
Respira CLI is a modern command line interface built for developers working with Claude Code, Cursor, and AI coding agents. It reads and writes Elementor, Divi, Bricks, WooCommerce, and eight more builders in their native formats. Every write is snapshot-backed, every result is one JSON envelope with a fixed exit code, and respira doctor says what is wrong before an agent guesses. Not a WP-CLI replacement, by design.
$ respira auth login opening browser to sign in... waiting for confirmation ✓ welcome, mihai@respira.press you're signed in. $ respira sites list read ~/.respira/sites.json id name url builder status ────── ────────── ────────────────────── ───────── ───────── s_1a2b mainblog https://mainblog.com elementor connected s_9f3c shop https://shop.example gutenberg connected s_4d7e clientsite https://clientsite.com divi connected $ respira sites fleet name url pluginVersion tokenStatus team ────────── ────────────────────── ───────────── ─────────── ──── mainblog https://mainblog.com 9.1.32 active no shop https://shop.example 9.1.32 active no clientsite https://clientsite.com unknown active yes 3 sites site keys omitted. add --with-keys --output json to include them. $ respira read design-system example.com { "site": "https://example.com", "colors": [ { "name": "primary", "value": "#3d9a8b" }, ... ], "fonts": [ { "role": "body", "family": "DM Sans" }, ... ], "detectedBuilder": "elementor" } $ respira find-element example.com home --type=heading --text="welcome" id type text path ───── ─────── ──────────── ────────────────────────────── hd-42 heading Welcome home section[0].column[0].widget[0]
A framework, not a command wrapper
Respira CLI is built on a six-phase execution cycle. Every command you run moves through the same deterministic runtime: load context, pre-hooks, resolve, execute, post-hooks, return. You see the output. Underneath, there is a framework.
The execution cycle
Six named phases. Every command runs through all of them. Nothing skips phases. Nothing reorders them. Deterministic by design, traceable with --verbose.
The hook framework
Five framework-level hook points are live: before_resolve, filter_plan, before_execute, filter_result, after_execute. In v0.1 no callbacks register here yet. The contracts are frozen. v0.2 adds callback registration and extension manifests on top, without changing anything you see in v0.1.
Tool Chain Functions
Every command is a typed function with a capability class, domain tags, and prerequisite declarations. Read, write, or destructive. Elementor, pages, write. Site connected and licensed. The cycle reads these and routes accordingly.
Structured tracing
--verbose on any command emits a JSON trace of the invocation: which phase ran, how long each took, what the tool chain function received and returned. Saved to ~/.respira/traces/. Useful when a coding agent needs to understand why something did or did not do what was expected.
The part most users care about: none of this changes how you use the CLI. Same commands. Same flags. Same output. The architecture is there because v0.2 is going to need it, and retrofitting it later would break everyone who had adopted v0.1. Landing it now, while no one is subscribed to the framework hooks, costs nothing downstream.
Respira CLI complements WP-CLI
WP-CLI is excellent for server-side WordPress administration. Built by the WordPress community over a decade. Respira CLI is a different category: it runs locally, understands page builder content natively, and is designed for AI coding agent workflows. Use WP-CLI for server maintenance. Use Respira CLI for builder-native content work driven by agents.
The WordPress CLI that understands your page builder
Every major builder, plus WooCommerce. Same command surface. Same safety workflow. These eleven are also the ones respira read structure recognizes on a public URL with no account. On a connected site the CLI calls the Respira plugin, so it reaches all 17 builders the plugin supports.
Elementor CLI
Read and edit Elementor trees, widgets, typography, templates, dynamic tags.
respira read page site about Divi CLI
Divi 4 shortcodes and Divi 5 blocks, both parsed into structured JSON.
respira read page site home --as=html Bricks CLI
Element tree with global-class awareness and ACSS integration.
respira find-element site home --type=heading WPBakery CLI
WPBakery shortcodes, rows, columns, edited as structured data.
respira read page site contact --as=builder Beaver Builder CLI
Modules, rows, templates with node-id preservation.
respira read pages site --builder=beaver Oxygen CLI
Oxygen element tree, style sets, selector resolution.
respira read design-system site Breakdance CLI
Breakdance modules and global settings from the terminal.
respira read page site landing Brizy CLI
Brizy blocks and global styles, addressable by id.
respira find-element site about --css=".hero-title" Thrive Architect CLI
Thrive Architect elements and conversion blocks.
respira read page site landing Flatsome CLI
Flatsome UX Builder elements and shortcodes.
respira read pages site --builder=flatsome Gutenberg CLI
Native WordPress blocks with attribute-level editing.
respira read page site home WooCommerce CLI
Products as a post type from the CLI, the rest of the store through the add-on.
respira read posts site --type=product --limit=100 Elementor CLI
Respira CLI ships with the deepest Elementor support of any command line tool. The element tree is parsed as JSON, ids are preserved across edits, and the distinction between the global kit and inline widget settings is honored. Typography, spacing and responsive breakpoints are all addressable, tablet and mobile control siblings included.
Elementor Pro objects the plugin already handles come along: theme builder templates and the saved template library. Safety is built in: every write snapshots first, and --dry-run previews without committing.
Divi CLI
Divi 4 shortcodes and Divi 5 blocks are both handled. The plugin reports which builder a site runs, so respira sites info tells you what you are working with instead of you guessing. Editing Divi from a terminal used to mean wrestling with raw shortcode strings. Respira parses them into structured JSON so you target attributes, not regexes.
Modules are addressable by id. respira find-element locates one, respira write edit-element sets attributes on it, and @respira/sdk exposes read.diviModule for scripts you run through respira exec. Works on every managed host.
Bricks CLI
Bricks Builder stores content as a flat array of element objects with parent references. Respira CLI reads this structure natively, preserves element ids across edits, and exposes global classes as first-class entities.
Every Bricks element type is supported: sections, rows, columns, headings, text, images, repeaters, query loops, dynamic data, custom elements from Bricks-compatible plugins. ACSS variables are detected when present and surfaced in the design system.
WPBakery CLI
WPBakery's shortcode structure is parsed into a structured tree so you can edit rows, columns, and module attributes directly. Respira CLI preserves shortcode ordering and comment fidelity that downstream plugins depend on.
TagDiv Composer sites are detected as WPBakery variants. Visual Composer legacy shortcodes round-trip cleanly.
WooCommerce CLI for AI-assisted store management
Products are a post type, so the CLI reaches them with the commands you already know: respira read posts --type=product lists them, respira write create-post --type=product creates them. The rest of the store graph, orders, coupons, shipping zones, tax classes and store settings, lives in the Respira WooCommerce add-on and its 104-tool catalog, which the same agent calls through the MCP server alongside the CLI.
Catalog work is scriptable. Filter with --type, --search and --limit. Create a product from a Markdown file and the title comes from the frontmatter or the first H1. For anything bulk, respira exec runs a TypeScript file with @respira/sdk bound as a global, so one script walks the catalog and applies edits call by call. Every write is snapshot-backed so a bad bulk change rolls back.
Built for Claude Code, Cursor, and AI coding agents
Respira CLI is the WordPress CLI for AI coding agents. It pairs with the Respira MCP server so Claude Code, Cursor, Codex, OpenCode, Hermes Agent, and GitHub Copilot CLI all drive the same builder-native tool surface.
Claude Code
One command installs a skill that points Claude Code at respira guide, the agent guide bundled with the installed version, and at sites list and doctor before the first write.
respira init-claude-code Cursor
Terminal-first or MCP-native. Same tool surface either way.
respira read structure mysite.com | pbcopy Codex
JSON-first output. Shell out and post-process with jq.
respira sites list --output=json | jq '.[].url' Copilot CLI
Shell-friendly. Every command emits JSON when piped.
respira read design-system mysite.com Hermes Agent
The open-source agent from Nous Research. Shell out to the CLI, or wire the MCP server into ~/.hermes/config.yaml.
hermes mcp login respira OpenCode
The free, open-source terminal agent from SST. Shell out to the CLI, or add the MCP server to opencode.json. freecode runs the same engine.
opencode mcp list Setup guides: Claude Code, Cursor, Hermes Agent.
How Respira CLI works
Install the CLI
One command from npm. Node.js 18 or later. Works on macOS, Linux, and Windows.
npm install -g @respira/cli Authenticate once
respira auth login opens your browser and stores your account key in your OS keychain. Each connected site's key lives there too, under the service respira-cli; ~/.respira/sites.json keeps only names and URLs. CI uses RESPIRA_API_KEY.
respira auth login Check the setup
respira doctor checks this machine, the account and every connected site, and exits 0 only when nothing fails. respira guide prints the agent guide for the installed version: core, safety, troubleshooting and the command list.
respira doctor Run commands
Call Respira CLI against any site connected through the plugin. No SSH, no FTP, no database access required. --mode direct sends site calls straight to the plugin, with nothing about the site passing through respira.press.
respira read page mysite.com about Install the WordPress CLI
npm
npm install -g @respira/cli pnpm
pnpm add -g @respira/cli yarn
yarn global add @respira/cli Full docs
Read the docs →Common questions
How is this different from WP-CLI?
WP-CLI runs on your WordPress server and is the right tool for server-side administration. Respira CLI runs on your local machine, talks to the Respira plugin over HTTPS, and understands page builder content natively. The two are complementary.
Does it require SSH?
No. Respira CLI never touches your server directly. It talks to the Respira plugin via HTTPS.
Does it work on managed hosts?
Yes. Because there is no SSH requirement, Respira CLI works on every major managed host: WP Engine, Kinsta, SiteGround, Cloudways, Pressable, Pantheon, Flywheel.
Is it open source?
Yes. MIT license. Source at github.com/respira-press/respira-wordpress-cli.
What does it cost?
Public reads (respira read structure, respira read design-system) against any public site are free with no account. Writes require a Respira license. See the pricing page.
Do I need Claude Code or another agent to use it?
No. The CLI is a standard command line tool that works on its own. Agent integrations are optional.
Can I use it in CI?
Yes. Set RESPIRA_API_KEY in your CI environment and every command runs headlessly. JSON output is the default when stdout is not a TTY.
What does a failure look like to an agent?
One JSON envelope, the same for every command. With --json or a piped stdout, success is { ok: true, data, meta } and failure is { ok: false, error, meta }, where error carries a code, a message, a hint, retry_ok and cause. Each code maps to a fixed exit code: 0 ok, 1 internal or far side, 2 the call, 3 credential, 4 plan, 5 site, 6 rate limit, 7 doctor checks, 130 cancelled. A missing argument is USAGE with exit 2 and a --help hint. Table and yaml output stay for people.
What does respira doctor check?
This machine, the account and every connected site, and it exits 0 only when nothing fails. Offline: the Node version, the credential backend, file modes under ~/.respira, the sites store, where the site keys live and the transport mode. Online it adds respira.press (reachable, clock skew, token accepted) and, per site: reachable, plugin version against the minimum, the ?rest_route= form, whether an Authorization header reaches PHP, the stored key against the plugin, and the plugin's own diagnostic report. Warnings still exit 0; a failure exits 7 with the report under error.details. No check prints a key.
Where are my site keys stored?
In the OS keyring, under the service respira-cli, next to your account token: macOS Keychain, Windows Credential Manager or libsecret on Linux. ~/.respira/sites.json keeps only names and URLs. A keyring that blocks on a permission prompt is a timeout and a message, never a hang, and RESPIRA_KEYRING=off keeps the keys in the 0600 file instead.
Does my site traffic go through respira.press?
Your choice. cloud is the default. --mode direct, or RESPIRA_MODE=direct, sends every site call straight to the plugin's REST API with the stored site key, so nothing about the site passes through respira.press. Account calls (auth, fleet, tools, docs, the public reads) go to respira.press in both modes, and the envelope's meta says which mode answered.
How do I see every site on my account, not just this laptop?
respira sites list reads ~/.respira/sites.json, so it only shows what this machine has connected, and it prints the path of the file it read so an empty list is never ambiguous. respira sites fleet asks your account instead and returns every site, including team sites, with the plugin version and token status each one reports. Site keys are left out unless you add --with-keys.
Which page builders are supported?
Elementor, Divi 4, Divi 5, Bricks, WPBakery, Beaver Builder, Oxygen, Breakdance, Brizy, Thrive Architect, Flatsome UX Builder and native Gutenberg blocks have named CLI surfaces on this page, plus WooCommerce through the Respira WooCommerce add-on. Those eleven are also what respira read structure detects on a public URL with no account. On a connected site the CLI calls the Respira plugin, so it reaches all 17 builders the plugin supports.
What is the execution cycle?
Every respira command runs through six phases: load context, pre-hooks, resolve, execute, post-hooks, return. It is deterministic, fully traced with --verbose, and extensible in v0.2 via callback registration at phase boundaries. You do not need to know any of this to use the CLI. It matters when you want to extend it.
37 commands, 45-tool catalog, 360+ MCP tools. Which is which?
37 is the number of user-facing respira commands (respira auth login, respira read page, respira write edit-element, respira doctor, respira guide, ...). 45 is the size of the local tool catalog you can browse with respira tools list / describe / search, scoped to what the CLI exposes today for builder and content operations. 360+ is the full Respira MCP server surface the WordPress plugin publishes, which includes every tool the desktop MCP server can call beyond the CLI’s current reach. They are consistent by design: CLI commands wrap a subset of the tool catalog, which is itself a subset of the MCP surface.
Can I extend the CLI with custom workflows or callbacks?
Starting in v0.2. The hook framework scaffolding is in place now, five framework-level hook points are live in v0.1 but have no callbacks registered. v0.2 adds extension manifests and callback registration on top, without changing anything in v0.1 API. If you are building against respira today, nothing you write will need to change when v0.2 arrives.
What is in v0.2?
Callback registration against framework-level hooks. Extension manifests for third-party contributors. SQLite-backed tool registry with full-text search. Tool chain functions declaring internal hook points. Baseline site inventory for per-site prerequisite validation. Roadmap lives in the GitHub repo.
Get started
One command. No signup required to read public sites.
WordPress is a registered trademark of the WordPress Foundation. Respira CLI for WordPress is an independent open-source project and is not affiliated with, endorsed by, or sponsored by WordPress.org, Automattic, or the WordPress Foundation.
