The forgewp command-line interface is the primary operational tool for managing, developing, and exporting ForgeWP themes. It is executed via your package manager in the root directory of any ForgeWP project (pnpm forgewp <command>, npx forgewp <command>, or bun x forgewp <command>).

Commands are organized into five primary functional categories:

1. Build & Export Commands

forgewp export

Compiles your React, TypeScript, and Tailwind CSS project into an installable PHP-backed WordPress hybrid theme with block-editor integration.

CLI Flags

Examples

forgewp analyze

Scans your project's components and generates a detailed report on selective hydration islands, bundle chunk sizes, and client runtime overhead.

What It Checks

1. Identifies all interactive components extracted into .forgewp-islands/.
2. Resolves Rollup chunk mappings from dist/.vite/manifest.json.
3. Reports client JavaScript bundle weights per route.
4. Alerts you if any unhydrated components contain DOM event listeners or state hooks.

2. Project Health & Maintenance

forgewp doctor

Executes comprehensive preflight diagnostic checks across your project to verify runtime environments, configuration, and internal framework files.

Diagnostic Checks Performed

• Node.js Runtime Environment: The doctor checks Node.js ^22.18.0 || >=24.11.0, matching the compiler dependencies. See System Requirements to choose a compatible version.
• User Configuration & Layout: Confirms presence and validity of wp.config.ts, package.json, index.html, and adapter critical files.
• Mock Database Schema: Validates syntax and presence of cms/mock-data.ts or cms/mock-data.json.
• System Framework Integrity: Compares hidden framework internal bridges against standard system blueprints.
• Hydration Diagnostics: Scans for static lint issues, such as unhydrated interactive event handlers inside <WpQueryLoop>.

forgewp repair

Automatically restores missing or corrupted internal framework blueprint files and virtual bridges.

What It Does

• Restores internal framework files and virtual bridges back to their pristine template state.
• Preserves your typed TypeScript schemas (cms/*.ts files are never overwritten).
• Re-seeds default starter posts in cms/mock-data.ts if the database file was deleted.

forgewp clean

Clears compiler caches, build directories, and temporary artifacts.

Pruned Directories

• .forgewp/ (build cache and packaged export output)
• dist/ (compiled Vite assets)
• .vite/ (Vite dev server cache)

forgewp fresh

Factory resets the project to a clean slate, removing custom scaffolded pages and blocks while restoring default starter blueprints.

3. Code Scaffolding Commands (make:*)

Scaffolding commands create type-safe components, block definitions, page templates, and schemas with best-practice folder conventions.

forgewp add <component>

Installs pre-built UI components from the ForgeWP component registry into src/components/ui/.

Options

• --style=shadcn|forgewp: Specifies design token preset.
• --overwrite: Replaces existing local component files.

Examples

forgewp make:block <Name>

Scaffolds a custom Gutenberg block in src/blocks/<Name>.tsx configured with defineBlock().

Example

This writes editable React source at src/blocks/TestimonialCard.tsx, with string attributes, editor controls, and starter visitor markup. It does not generate PHP at scaffold time. Export compiles that source into WordPress block metadata, PHP rendering, and shared editor assets. Attribute names must be unique JavaScript property identifiers, such as title or cta_label; change field types and controls in the generated source when needed.

Run pnpm forgewp make:block --help for options and the authoring-path guide. Help works outside a theme without creating files or asking for a name.

forgewp make:page <Name>

Scaffolds a custom WordPress Page Template in src/app/pages/<Name>.tsx.

This creates the React page component with an exported pageConfig, registers the route in src/app/routes.tsx, and enables WordPress template selection in wp-admin.

forgewp make:section <Name>

Scaffolds a reusable editable layout section that can be rendered inside a page or registered as a standalone Gutenberg block.

forgewp make:shell <Name>

Scaffolds a multi-column parent container block supporting child blocks via Gutenberg <InnerBlocks />.

forgewp make:island <Name>

Scaffolds an isolated client hydration component inside src/components/islands/<Name>.tsx.

forgewp make:editable <Name>

Scaffolds a colocated client-editable schema inside cms/editables/<slug>.ts with typed field definitions.

forgewp make:form <Name>

Scaffolds a native WordPress form schema in cms/forms/<name>.ts and a companion React form component in src/components/forms/<Name>Form.tsx.

forgewp make:post-type <slug>

Registers a custom post type in wp.config.ts and seeds initial mock items in cms/mock-data.ts.

forgewp make:loop <Name>

Generates a responsive card grid component wrapped in <WpQueryLoop> for a specific post type.

forgewp make:sandbox <type>

Seeds an offline mock database schema for specialized workflows.

4. Route & Data Synchronization

forgewp sync:routes

Scans your navigation menu definitions in cms/menus.ts and automatically scaffolds missing page templates in src/app/pages/ and route declarations in src/app/routes.tsx.

forgewp sync:hooks

Synchronizes isomorphic WordPress data hook types and definitions across multi-theme monorepositories.

forgewp seed

Preview mock-data seeding before changing configuration:

This loads wp.config.ts and the mock fixtures, then reports each post type's fixture count, enabled strategy, and normalized seed records, including slugs, serialized content, custom fields, and featured-image references. It uses the same record normalization as the PHP generator. Disabled or omitted post types have no seed records. When seeding is not configured, the preview leaves it disabled.

--json emits the report as JSON for tools (configuration warnings can still appear on stderr). The report includes developmentOnly and sideloadImages. It does not change files, export PHP, contact WordPress, download images, or inspect the database's seed markers or WP_DEBUG value. Actual activation behavior depends on those site conditions. Preview currently supports mock data only; product preview is outside this workflow.

Inspects local mock data and can add an initial seed configuration to wp.config.ts when no seed: block exists. It does not directly connect to MySQL or deploy a theme. Review the configuration and export/install the theme to generate and run WordPress-side seed routines.

To seed an installed theme using its generated routines, run the corresponding command on the WordPress host, where WP-CLI is installed:

These WP-CLI commands are registered only when their seeders are generated; the product seeder also depends on the WooCommerce integration. Normal guards still apply. Adding --force bypasses the development guard and seed/hash checks and can overwrite content. Review Database Seeding Strategies before using these on an existing site.

5. Internationalization Commands

forgewp i18n:extract

Scans all JSX components and templates for useWpI18n() calls, extracting all translation keys into cms/translations.ts in a sorted, non-destructive format.

forgewp i18n:translate

Translates missing language keys across your target locales using the machine translation provider configured in wp.config.ts (deepl, google, libretranslate, or local).

Translations are written back to the CMS translation catalog. The command selects empty values for translation and skips populated entries. Setting i18n.cache additionally enables a persistent response cache for successful translations. Cached matches fill blank catalog entries before requesting a provider. Remote requests may have their own costs and rate limits.

Summary of All Commands

Next Steps

Now that you have reviewed the forgewp CLI reference, proceed to the create-forgewp Scaffolder Reference to explore interactive project creation, non-interactive automation flags, and CI/CD project initialization.

Additional flags and automation details

There are 25 canonical command keys in the current CLI dispatcher, including seed:products and seed:mock-data. Some share an implementation. Use pnpm forgewp --help for the command list; only commands that implement their own help parser should be called with subcommand --help.

The dispatcher also recognizes convenience aliases such as make-block, make-section, section, shell, page, island, loop, post-type, editable, form, sandbox, sync-routes, sync-hooks, i18n-extract, i18n-translate, reset (fresh), and inspect (analyze). Prefer canonical colon-form commands in scripts and documentation.

seed:products and seed:mock-data dispatch to the same seeder script as seed; the dispatcher does not insert a positional target. For an explicit selection, use pnpm forgewp seed products or pnpm forgewp seed mock-data. This local command inspects CMS source and can add a missing seed block to wp.config.ts; export afterward to regenerate the theme's PHP seeders. The separate wp forgewp seed-products / seed-mock-data commands run inside WordPress when registered.

Command effects matter in automation: add --overwrite, route sync with force, sync:hooks, repair, and fresh can write or replace source. Review the affected paths and keep a commit or backup before running them. clean also removes packaged exports inside .forgewp/, so keep release artifacts elsewhere.

make:mail

Creates cms/mail/contact-receipt.json with plain-text subject and body defaults. Run it from the theme root containing wp.config.ts. Existing files are preserved. Reference the name using a native form's notificationTemplate or confirmation.template; per-form text overrides the source defaults, and saved WordPress admin edits take priority. The Native Forms guide includes a complete configuration example.