Introduction
brmbh is an open-source WordPress starter theme — Bootstrap 5, Gutenberg, and an ACF
block factory — with agent skills baked in. The @brmbh/cli package is its command-line
front door: it scaffolds a project, generates blocks and post types, builds assets, and deploys.
The whole experience is one install command plus a handful of verbs. Every command runs in two modes:
a friendly human mode by default, and a structured --json mode that an AI agent can drive.
See Agent / JSON mode.
Requirements
- Node ≥ 18 — the CLI is pure ESM with zero runtime dependencies.
- git — used to clone the theme (or use
--fromto copy a local checkout). - Secure Custom Fields (SCF) — free, required for ACF blocks. Install from wordpress.org/plugins/secure-custom-fields. ACF Pro also works.
- wp-cli (optional) — enables automatic theme activation and ACF detection.
Installation
You don't install brmbh globally — you run it on demand to scaffold a project:
# scaffold a new theme into ./my-site
npx @brmbh/cli create my-site
To use the lifecycle commands inside a project, run them through npx or add a script:
npx @brmbh/cli doctor npx @brmbh/cli add block hero
Quick start
1. cd wp-content/themes 2. npx @brmbh/cli create my-site # clone, install, build, skills, activate 3. # open your editor + Claude/Cursor; the skills are ready 4. npx @brmbh/cli deploy staging
After step 2 you have a working, activated theme with agent skills wired into .claude/,
.cursor/, and .windsurf/. In your AI editor, try:
“create a hero block from this Figma frame.”
create L3
Scaffold a new brmbh theme into a folder: materialize the theme, install dependencies, build assets, wire the agent skills, check for SCF, and activate the theme when running inside a WordPress install.
npx @brmbh/cli create [name] [flags]
| Flag | Description |
|---|---|
--from <path> | Copy the theme from a local checkout instead of cloning (offline). |
--ref <branch> | Git branch or tag to clone (default: repo default branch). |
--skip-install | Skip npm install + build. |
--skip-activate | Skip wp-cli theme activation. |
--force | Scaffold into a non-empty folder. |
# standard npx @brmbh/cli create my-site # offline, from a local checkout, no install npx @brmbh/cli create demo --from ../wordpress --skip-install
next array — a literal, ordered
list of follow-up steps an agent can execute verbatim (e.g. install SCF, activate the theme).
add block L3
Scaffold a new ACF block following the four-file factory convention, and register its SCSS import. The block self-registers — no manual wiring.
brmbh add block <name> [flags]
| Flag | Description |
|---|---|
--mode <preview|edit> | Default editor display. preview (default) shows the rendered block with a “Switch to Edit” toggle. |
--force | Overwrite if the block already exists. |
Creates my-acf-blocks/<name>/ with:
block.json— WordPress-standard registration (apiVersion: 2,supports.mode).fields.php— ACF field group, returned as an array.template.php— render template (Bootstrap utilities + design tokens)._style.scss— block styles, auto-imported via_loader.scss.
brmbh add block hero brmbh add block feature-grid --mode edit
add cpt L3
Scaffold a custom post type as a single file in inc/post-types/, and ensure functions.php auto-loads it (idempotent).
brmbh add cpt <name> [flags]
| Flag | Description |
|---|---|
--plural <label> | Plural label (default: name + “s”). |
--force | Overwrite if it already exists. |
Defaults follow the suite's CPT pattern: public: false, show_ui: true, show_in_rest: true, has_archive: false, supports title / thumbnail / revisions. Reference the CPT from a block via an ACF relationship field.
brmbh add cpt speaker brmbh add cpt category --plural "Categories"
add skills L3
(Re)generate the per-agent skill wrappers from the canonical AGENTS/*.md skills. One source of truth, three sets of thin wrappers — this kills the duplication of maintaining skills by hand across editors.
brmbh add skills
Generates, for each AGENTS/<name>.md:
.claude/commands/<name>.md.cursor/rules/<name>.mdc.windsurf/rules/<name>.md
dev L1
Run the theme's asset pipeline. Watches by default; builds once with --once.
brmbh dev # watch CSS + JS brmbh dev --once # single build, then exit
doctor L2
Check that the theme and environment are correctly wired. Returns a single class — ready, warn, or blocked — plus the individual checks, so an agent can branch deterministically.
brmbh doctor brmbh doctor --json
Checks: node version, theme detected, dependencies installed, assets built, skills present, environments, wp-cli availability, and SCF status.
# --json output { "ok": true, "message": "Environment: warn", "class": "warn", "checks": [ { "name": "node", "status": "ok" }, { "name": "build", "status": "warn" } ] }
update L2
Bring a site to the newest brmbh: update @brmbh/cli (commands and agent skills), replace the core in inc/core/, and run any migration a release ships for your own files.
npx brmbh update # update in range, replace inc/core/, run migrations npx brmbh update --latest # also take a new major version npx brmbh update --dry-run # show what would change, write nothing
| Part of the theme | What update does |
|---|---|
inc/core/ — block factory loader, SCF guard, wp brmbh commands | Replaced as a whole. Never edit it; extend it with hooks such as brmbh/block_dirs. |
Your templates, blocks, styles, inc/ files | Never overwritten. A release that needs a change ships a migration you review. |
| Commands and agent skills | Updated with @brmbh/cli. |
update writes nothing and returns class: "blocked" with the file and the fix. doctor reports a missing, outdated or hand-edited core.
Environments
An environment is a named place the site runs: any number, any names (staging, production, review). They are defined in the theme's project config, and every command that talks to a server takes the name.
| File | What it holds |
|---|---|
brmbh.json | Committed. Environments the whole team shares, and deploy settings. |
brmbh.local.json | Gitignored. Overrides brmbh.json key by key on this machine, e.g. hosts that should stay out of git. |
# brmbh.json { "environments": { "staging": { "ssh": "deploy@staging.example.com", "path": "/var/www/staging", "url": "https://staging.example.com", "canonical": "local" }, "production": { "ssh": "deploy@example.com", "path": "/var/www/html", "url": "https://example.com", "canonical": "remote" } }, "deploy": { "include": ["assets/dist"] } }
| Key | Meaning |
|---|---|
ssh | SSH target (user@host or an alias from ~/.ssh/config). Keys come from the machine or a CI secret, never from the config. |
path | The WordPress root on the server. |
url | The public URL, used to check the site after a deploy. |
canonical | Which side holds the real content: remote (default) or local. Pushing the database or uploads is only allowed onto a local-canonical environment. |
excludes | Upload folders to skip when syncing, e.g. ["videos"]. |
How the commands reach a server: the CLI reads the environment, logs in with your own SSH setup (~/.ssh/config, ssh-agent or a CI secret) and runs WP-CLI there. The server needs SSH access, WP-CLI as wp, and rsync for deploy and uploads. Paths with spaces are fine.
tools/env/*.env? brmbh update moves those files into brmbh.local.json and gitignores it. The files are read as data, never executed.
deploy L2
Deploy a commit of the theme to an environment. The same command runs on a laptop and in CI.
npx brmbh deploy staging # dry run: lists new, changed and deleted files npx brmbh deploy staging --apply # send, then check the live site
- A commit, not a working tree. Uncommitted changes stop the deploy.
- Build with
npm run build. - Stage the tracked files plus the build output (
deploy.include), without development files (assets/src,package.json,AGENTS.md, the config files). - Dry run by default. Only
--applysends; files removed in git are removed on the server. - Flush the object cache on the server (
wp cache flush). - Verify. The live
brmbh-deploy.jsonmust carry the commit just sent, and the home page must load without a PHP error.
| Flag | Description |
|---|---|
--apply | Send the files. Without it nothing is sent. |
--skip-build | Deploy the build output as it is. |
--allow-dirty | Deploy uncommitted changes; recorded as dirty in the stamp. |
The class is would_deploy, up_to_date, deployed or verify_failed (the files were sent, but the live check failed). A site behind a password (401/403) is reported as not verified.
db L2
Move the database between this machine and an environment. Code flows up, content flows down: canonical decides which way is allowed.
npx brmbh db pull production # server → this machine npx brmbh db push staging --yes # this machine → server, only onto canonical: "local"
Both directions need local.url in brmbh.local.json: every URL in the database is rewritten to it, so it is never guessed.
What db pull does
- Checks both connections with
wp db check, locally and over SSH. If one fails, nothing has changed yet. - Backs up the local database to
.brmbh/backups/local-before-<env>-<time>.sql.gzin the theme (gitignored). - Copies the database:
wp db exporton the server streams over SSH straight intowp db importon this machine. No dump file stays on the server. - Rewrites URLs from the server's
urltolocal.urlin all tables, forhttps://andhttp://, then once more to catch leftovers. Serialized data (widgets, field values) stays valid. - Repairs the site: sets
siteurlandhome, activates the local theme, flushes the cache. - Matches plugins: installs exactly the plugin versions the server runs, never newer ones. A premium plugin that isn't on wordpress.org is named, so you copy it yourself.
- Runs pending database upgrades (
wp core update-db) and reports any version drift between this machine and the server.
What db push does
- Checks the direction: refused unless the environment is
"canonical": "local". The default isremote, so content entered on a live site is never overwritten by accident. - Asks first. In the terminal it asks for confirmation; an agent (
--json) getsconfirm_requiredand has to ask you before it runs again with--yes. - Checks both connections.
- Backs up the server's database to
~/.brmbh-backups/<env>-before-push-<time>.sql.gzon the server, outside the web root. An empty backup stops the push. - Copies the database: exports locally, uploads it to a temporary file on the server, imports it and deletes the file.
- Rewrites URLs from
local.urlto the server'surl, and repairssiteurl,home, theme, cache and database upgrades on the server.
wp db import local-before-production-….sql.gz after unzipping it.
uploads L2
Sync wp-content/uploads with rsync over SSH, with the same direction rules as db.
npx brmbh uploads pull production # adds what's missing locally npx brmbh uploads pull production --exclude=videos # skip a folder this run npx brmbh uploads pull production --delete # mirror exactly npx brmbh uploads push staging --dry-run # show what would change npx brmbh uploads push staging --yes # mirror local onto the server
- pull only adds and updates files. Files that exist only on this machine stay, unless you pass
--delete. - push makes the server's uploads an exact copy of yours, so files that exist only on the server are removed. First it lists how many files are new, replaced and deleted (with the names of deleted ones). Then it sends, and every file it replaces or deletes is moved to
~/.brmbh-backups/uploads-<env>-before-push-<time>/on the server instead of being lost. - Folders that never sync (a backup plugin's storage, large videos) go in the environment's
excludes;--excludeadds more for one run.
env L1
List the environments and where each is defined, or run a tool against one.
npx brmbh env # list npx brmbh env run production version-check # compare WordPress, PHP, plugin and theme versions with local npx brmbh env run staging db-verify # test both database connections, change nothing npx brmbh env run staging sync-plugins # install the locally active plugins there
add ci L3
Optional. Writes a GitHub Actions workflow that runs the same brmbh deploy, started by hand from the Actions tab. Nothing is set up by default; where and how a site deploys is up to you and your agent.
npx brmbh add ci github # writes .github/workflows/deploy.yml
Agent / JSON mode
Every command supports --json. Instead of human output, it prints a single JSON
envelope on stdout and always exits 0 — so an agent reads the
ok field rather than parsing exit codes or prose.
# success { "ok": true, "message": "Added block \"Hero\"", "slug": "hero", "next": [ ... ] } # failure (still exit 0) { "ok": false, "error": "Block already exists", "code": "exists" }
Each command declares a level describing how to use its result:
| Level | Returns | The caller… |
|---|---|---|
| L1 data | raw facts | interprets and decides |
| L2 classification | a class field | branches deterministically |
| L3 instructions | a next procedure | executes it verbatim |
Introspection is built in:
brmbh schema # machine-readable schema of every command brmbh <command> --help # human help for one command
Secure Custom Fields (SCF)
create and doctor detect it automatically via wp-cli.
SCF is the WordPress.org-maintained fork of ACF Pro — same API, same block registration, same field functions.
ACF Pro also works if you already have a license. brmbh recognizes both
secure-custom-fields and advanced-custom-fields-pro.
Architecture
brmbh follows a code-first split: deterministic work lives in the CLI (generating files, wiring registrations, running builds); the reasoning — turning a screenshot or Figma frame into ACF fields and markup — stays with the agent skill in the theme.
So a block is built in two halves:
- CLI (deterministic):
brmbh add block herowrites the four files and registers the SCSS import. - Skill (reasoning): your agent reads the design, infers the field schema, and fills
fields.php+template.phpusing Bootstrap utilities and design tokens.
The CLI itself is a thin code-first runtime: a dispatcher with dual-mode output, the level system, schema/help introspection, and a stable error contract. It has zero runtime dependencies.
bin/brmbh.js # entrypoint src/tool.js # dispatcher: dual-mode, levels, schema src/commands/*.js # create, add, dev, doctor, update, deploy, db, uploads, env templates/{block,cpt}/* # scaffold templates
FAQ
Do I need to install the CLI globally?
No. Run it with npx. Nothing is installed globally.
Can I use it offline?
Yes — pass --from <local-checkout> to create to copy the theme from disk instead of cloning.
Which AI editors are supported?
Claude Code, Cursor, and Windsurf get generated wrappers; skills are authored once in AGENTS/. With npx skills add brmbh/wordpress the skills also install in 30+ other agents.
Is it tied to a specific host?
No. Environments are SSH targets you name in brmbh.json; any host with SSH and rsync works, from a laptop or from CI.