Skip to main content

Command Reference

Run these commands from the devkit root unless noted otherwise.

Project Setup​

/new-project​

Starts the agent-guided onboarding flow. Use it when creating or binding a LocalWP-backed project.

/new-project

The flow matches a Local site, infers a project slug, creates projects/<slug> when needed, binds it, checks it, syncs it, runs readiness checks, and records project notes.

localwp:list​

Lists LocalWP sites visible on the machine.

bun run localwp:list

Use this before binding when you need the exact Local site name, domain, or path.

project:create​

Creates a project from the devkit project template.

bun run project:create -- my-site

The slug must use lowercase letters, numbers, and dashes. The command fails if the project already exists.

localwp:bind​

Binds a project to one Local site.

bun run localwp:bind -- --project my-site --site "My Site"

You can also bind by site ID or web root when needed:

bun run localwp:bind -- --project my-site --site-id <local-site-id>
bun run localwp:bind -- --project my-site --web-root "/Users/me/Local Sites/my-site/app/public"

Binding writes the Local web root and target plugin path into projects/my-site/project.json.

Build and Sync​

project:check​

Checks the project runtime source before sync or packaging.

bun run project:check -- --project my-site

Run this before every sync after changing src/** or cms/**.

localwp:sync​

Copies checked runtime plugin files into the bound Local site.

bun run localwp:sync -- --project my-site

Sync output goes to the Local site plugin path:

wp-content/plugins/oh-my-idetch

LocalWP and WordPress Inspection​

localwp:wp​

Runs WP-CLI through Local's Site Shell environment when available.

bun run localwp:wp -- --project my-site -- plugin list
bun run localwp:wp -- --project my-site -- plugin is-active oh-my-idetch
bun run localwp:wp -- --project my-site -- option get home

If Local has not generated the shell entry, open Local, select the site, choose Open Site Shell, and run the printed fallback command manually.

localwp:doctor​

Reports project and Local site readiness.

bun run localwp:doctor -- --project my-site

It checks binding, web root availability, WP-CLI availability, WordPress environment type, synced plugin state, plugin activation, and runtime plugin status when WP-CLI works.

localwp:capabilities​

Prints JSON describing active runtime capabilities.

bun run localwp:capabilities -- --project my-site

Use it before assuming Etch, OhMyEtch, AutomaticCSS, CMS fields, or WooCommerce support exists in the bound Local site.

localwp:verify​

Runs the fast read-only runtime verification after sync.

bun run localwp:verify -- --project my-site

It checks the compiled entity/resource digests, recorded ownership, required active capabilities, and the installed Builder contract, without browser E2E. Add one lightweight frontend availability check only when it is part of the task:

bun run localwp:verify -- --project my-site --path /

Devkit Updates​

devkit:update​

Plans and applies updates from a newer devkit ZIP. Always dry-run first:

bun run devkit:update -- --zip /path/to/oh-my-idetch-localwp-devkit-<version>.zip

Apply the update after reviewing the plan:

bun run devkit:update -- --zip /path/to/oh-my-idetch-localwp-devkit-<version>.zip --apply

The updater never changes projects/**, .git/**, .env*, node_modules/**, dist/**, or var/**. It updates only devkit-owned tooling, generated agent guidance, and the project template.

Builder Authoring Queries​

Offline queries against the verified authoring knowledge of the pinned honestlydesign/etch-builders package. Use them to confirm the real builder API surface instead of guessing it.

builder:help​

Shows what an authoring capability allows:

bun run builder:help -- --intent <capability-id>

builder:component​

Looks up a component contract:

bun run builder:component -- --key <component-key>

builder:explain​

Explains a builder diagnostic code:

bun run builder:explain <diagnostic-code>

builder:escape​

Checks whether an intent has a sanctioned checked-escape path and prints its guidance:

bun run builder:escape -- --intent <capability-id>

CMS Commands​

CMS operations for the bound Local site. The project directory cms/acf-json/** is the source of truth for field groups.

cms:acf:status, cms:acf:sync, cms:acf:import, cms:acf:export​

bun run cms:acf:status -- --project my-site
bun run cms:acf:sync -- --project my-site
bun run cms:acf:import -- --project my-site
bun run cms:acf:export -- --project my-site

Report, sync, import, and export ACF field group JSON between the project and WordPress.

cms:rewrite​

Flushes WordPress rewrite rules through the checked wrapper:

bun run cms:rewrite -- --project my-site

cms:post:generate and cms:term:generate​

Generate posts and taxonomy terms for content modeling:

bun run cms:post:generate -- --project my-site
bun run cms:term:generate -- --project my-site

cms:media:import and cms:media:featured​

Import media files into WordPress and attach featured images to posts:

bun run cms:media:featured -- --project my-site -- --file=<path> --post_id=<id> [--title=<title>]

Packaging​

build:zip -- --project​

Checks and packages one project as a production plugin ZIP.

bun run build:zip -- --project my-site

The ZIP is written under:

projects/my-site/dist/oh-my-idetch-<version>.zip

Use this ZIP as the deployable project plugin artifact.