Skip to main content

Basic Usage

WP-Node includes a CLI tool that lets you interact directly with your WordPress database. You can retrieve or manipulate posts, users, terms, and more — all from your terminal.

Prerequisites​

Ensure you have a running WordPress-compatible database.

📖 See the Installation Guide for setting one up using Docker.

⚙️ Configuration Setup​

The CLI requires two files:

  • _wp/config/wp.json: WP-Node configuration
  • .env: Environment variables (like database credentials)

Create the config files​

Generate the config structure by running:

npx @rnaga/wp-node-cli -- config

You’ll be prompted to provide database hostname, username, password, etc.

File structure

./
├── _wp
│   └── config
│       ├── index.d.ts
│       └── wp.json
└── .env

🔍 See Configuration Guide for detailed reference.

📦 Adding CLI to NPM Project​

You can use the CLI with npx, but for better performance and convenience, install it in your project.

Step-by-step:​

mkdir /tmp/test-wp-node-cli & cd /tmp/test-wp-node-cli
npm init -y
npm i -S @rnaga/wp-node-cli

Add cli to scripts in package.json​

  "scripts": {
    "wp-node": "node node_modules/@rnaga/wp-node-cli/index.js"
  },

You can now use the CLI via npm run wp-node. For example, to fetch a post by ID:

npm run wp-node -- post get 1

📋 Listing Available Commands​

To view all available CLI commands, run:

npm run wp-node -- -h

output:

Usage: <command> <subcommand> [options]

Commands:
   blog             Blog commands
   comment          Comment commands
   config           Generate WP config files
   init             Initialize WP with Node. (Generate wp.json and install dependencies)
   install          Initialize a new blog and create a user
   meta             Meta commands (post, comment, blog, term, user, site)
   option           Options commands
   post             Post commands
   repl             Start a REPL
   role             Role commands
   site             Site commands
   term             Term commands
   user             User commands

ℹ️ You can append -h or --help to any CLIs (including subcommands) to view its options.

Example: Check post command help

npm run wp-node -- post --help

Output:

Usage: post <subcommand> [options]

Subcommands:
   get              Get a post by id
   create           Create a post
   update           Update a post
   delete           Delete a post
   list             List posts

🎛 Available Options​

-F — Select Fields​

Limit the fields returned in the output.

npm run wp-node -- post list -F ID,post_title

-Z — Output Format​

Control the output format: json, table, csv, or raw.

npm run wp-node -- post list -F ID,post_title -Z table

Use the -h or --help flag to display available options and usage details.