brmbh

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 --from to 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]
FlagDescription
--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-installSkip npm install + build.
--skip-activateSkip wp-cli theme activation.
--forceScaffold 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
Level L3. The JSON envelope includes a 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]
FlagDescription
--mode <preview|edit>Default editor display. preview (default) shows the rendered block with a “Switch to Edit” toggle.
--forceOverwrite 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
Deterministic skeleton, agent reasoning. The CLI lays down the files; your agent skill turns the design (screenshot or Figma frame) into the actual fields and markup. See Architecture.

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]
FlagDescription
--plural <label>Plural label (default: name + “s”).
--forceOverwrite 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 themeWhat update does
inc/core/ — block factory loader, SCF guard, wp brmbh commandsReplaced as a whole. Never edit it; extend it with hooks such as brmbh/block_dirs.
Your templates, blocks, styles, inc/ filesNever overwritten. A release that needs a change ships a migration you review.
Commands and agent skillsUpdated with @brmbh/cli.
Nothing half-done. If a migration needs you first (for example a starter file you edited), 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.

FileWhat it holds
brmbh.jsonCommitted. Environments the whole team shares, and deploy settings.
brmbh.local.jsonGitignored. 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"] }
}
KeyMeaning
sshSSH target (user@host or an alias from ~/.ssh/config). Keys come from the machine or a CI secret, never from the config.
pathThe WordPress root on the server.
urlThe public URL, used to check the site after a deploy.
canonicalWhich side holds the real content: remote (default) or local. Pushing the database or uploads is only allowed onto a local-canonical environment.
excludesUpload 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.

Coming from 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
  1. A commit, not a working tree. Uncommitted changes stop the deploy.
  2. Build with npm run build.
  3. Stage the tracked files plus the build output (deploy.include), without development files (assets/src, package.json, AGENTS.md, the config files).
  4. Dry run by default. Only --apply sends; files removed in git are removed on the server.
  5. Flush the object cache on the server (wp cache flush).
  6. Verify. The live brmbh-deploy.json must carry the commit just sent, and the home page must load without a PHP error.
FlagDescription
--applySend the files. Without it nothing is sent.
--skip-buildDeploy the build output as it is.
--allow-dirtyDeploy 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

  1. Checks both connections with wp db check, locally and over SSH. If one fails, nothing has changed yet.
  2. Backs up the local database to .brmbh/backups/local-before-<env>-<time>.sql.gz in the theme (gitignored).
  3. Copies the database: wp db export on the server streams over SSH straight into wp db import on this machine. No dump file stays on the server.
  4. Rewrites URLs from the server's url to local.url in all tables, for https:// and http://, then once more to catch leftovers. Serialized data (widgets, field values) stays valid.
  5. Repairs the site: sets siteurl and home, activates the local theme, flushes the cache.
  6. 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.
  7. Runs pending database upgrades (wp core update-db) and reports any version drift between this machine and the server.

What db push does

  1. Checks the direction: refused unless the environment is "canonical": "local". The default is remote, so content entered on a live site is never overwritten by accident.
  2. Asks first. In the terminal it asks for confirmation; an agent (--json) gets confirm_required and has to ask you before it runs again with --yes.
  3. Checks both connections.
  4. Backs up the server's database to ~/.brmbh-backups/<env>-before-push-<time>.sql.gz on the server, outside the web root. An empty backup stops the push.
  5. Copies the database: exports locally, uploads it to a temporary file on the server, imports it and deletes the file.
  6. Rewrites URLs from local.url to the server's url, and repairs siteurl, home, theme, cache and database upgrades on the server.
Undo: import the backup on the side that was overwritten, e.g. 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; --exclude adds 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:

LevelReturnsThe caller…
L1 dataraw factsinterprets and decides
L2 classificationa class fieldbranches deterministically
L3 instructionsa next procedureexecutes 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)

SCF is required for blocks — and it's free. Install it from wordpress.org/plugins/secure-custom-fields. 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:

  1. CLI (deterministic): brmbh add block hero writes the four files and registers the SCSS import.
  2. Skill (reasoning): your agent reads the design, infers the field schema, and fills fields.php + template.php using 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.

Still stuck? Open an issue on GitHub.