CLI
The WPNuxt CLI (wpnuxi) helps you create new projects, inspect your environment, and diagnose common issues.
Installation
The CLI is available as a standalone package or via npm create:
npx wpnuxi <command>
npm install -g wpnuxi
Commands
wpnuxi init
Scaffold a new WPNuxt project from the starter template.
npx wpnuxi init [directory]
When run without arguments, the CLI interactively prompts you for:
- Project name — directory to create (defaults to
my-wpnuxt-app) - WordPress URL — your WordPress site URL (defaults to
http://127.0.0.1:9400) - Package manager — pnpm, npm, yarn, or bun (auto-detects from current project)
- Initialize git — whether to create a git repository with an initial commit
When a directory argument is provided (e.g. npx wpnuxi init my-blog), the project name prompt is skipped and git is initialized automatically (use --skip-git to disable).
After scaffolding, it installs dependencies and writes a .env file with your WordPress URL.
Options
| Flag | Description |
|---|---|
--wordpress-url, -w | WordPress site URL (skips prompt) |
--pm | Package manager: npm, pnpm, yarn, or bun (skips prompt) |
--skip-install | Skip dependency installation |
--skip-git | Skip git initialization |
Example
npx wpnuxi init my-blog
This is equivalent to running npm create wpnuxt@latest — both use the same starter template.
wpnuxi info
Display environment and project information. Useful when reporting issues.
npx wpnuxi info
Example Output
WPNuxt Project Info
OS darwin arm64
Node.js v22.14.0
Package Manager pnpm
@wpnuxt/core ^2.0.0-beta.1
nuxt ^4.3.1
@nuxt/ui ^3.1.0
WordPress URL https://wordpress.wpnuxt.com
GraphQL Endpoint https://wordpress.wpnuxt.com/graphql
The command reads package.json for dependency versions and .env for the WordPress URL. Package manager is detected from the lockfile (pnpm-lock.yaml, yarn.lock, bun.lockb, or package-lock.json).
Options
| Flag | Description |
|---|---|
--cwd <path> | Run in a different directory (defaults to current directory) |
wpnuxi doctor
Run health checks on your WPNuxt project to diagnose common issues.
npx wpnuxi doctor
Checks Performed
| Check | Type | Description |
|---|---|---|
.env has WPNUXT_WORDPRESS_URL | Critical | Verifies the environment variable is set |
WordPress URL is valid | Critical | Checks the URL is a valid http/https URL |
GraphQL endpoint reachable | Critical | Tests that the GraphQL endpoint responds |
@wpnuxt/core in package.json | Critical | Verifies the core package is a dependency |
nuxt in package.json | Critical | Verifies Nuxt is a dependency |
WPGraphQL introspection enabled | Warning | Checks that GraphQL introspection is enabled |
Critical checks that fail cause the command to exit with code 1. Non-critical checks show a warning but don't fail the command.
Options
| Flag | Description |
|---|---|
--cwd <path> | Run in a different directory (defaults to current directory) |
Example Output
WPNuxt Doctor
[PASS] .env has WPNUXT_WORDPRESS_URL
[PASS] WordPress URL is valid
[PASS] GraphQL endpoint reachable
[PASS] WPGraphQL introspection enabled
[PASS] @wpnuxt/core in package.json
[PASS] nuxt in package.json
All critical checks passed.
npm create wpnuxt
A convenience wrapper around wpnuxi init. These commands are equivalent:
npm create wpnuxt@latest
npx wpnuxi init