Skip to content
Docs

WP-CLI Commands

BuddyPress Stats ships a WP-CLI command group (wp bp-stats) for test-data generation, health checks, diagnostics, and cleanup. These commands are intended for development and staging environments.

Important: The command class lives in tests/class-bp-stats-cli-commands.php and is loaded only when WP_CLI is defined and true and that file exists. tests/ is listed in .distignore, so the customer distribution zip does not include it: these commands are available only in a development checkout of the repository.

Command Overview

Section titled “Command Overview”
Command Description
wp bp-stats generate Create test users, groups, and activities
wp bp-stats populate_users Create users with configurable activity patterns
wp bp-stats summary Print a stats summary table
wp bp-stats health_check Verify plugin and database health
wp bp-stats test Run data, permissions, UI, and performance tests
wp bp-stats cleanup Delete test data created by the generate commands

wp bp-stats generate

Section titled “wp bp-stats generate”

Creates test users, groups, and activities in one pass.

Terminal window
wp bp-stats generate

Options

Section titled “Options”
Option Type Default Description
--users=<number> int 50 Number of test users to create
--groups=<number> int 10 Number of test groups to create
--activities=<number> int 5 Activities to create per user
--comprehensive flag off Generate a full dataset covering all activity types
--cleanup flag off Delete existing test data before generating new data

Examples

Section titled “Examples”
Terminal window
# Default test dataset.
wp bp-stats generate


# Comprehensive dataset covering all activity types.
wp bp-stats generate --comprehensive


# Large dataset, clean slate first.
wp bp-stats generate --users=200 --groups=30 --activities=10 --cleanup

Test users are tagged with the user meta key bp_stats_test_user = true, so they can be found and removed with wp bp-stats cleanup.

wp bp-stats populate_users

Section titled “wp bp-stats populate_users”

Creates users with realistic activity patterns (active, moderate, inactive, or mixed). Useful for testing the Retention Rate and User Health views with varied data.

Terminal window
wp bp-stats populate_users

Options

Section titled “Options”
Option Type Default Description
--count=<number> int 50 Number of users to create
--pattern=<type> string mixed active, moderate, inactive, or mixed

Pattern Definitions

Section titled “Pattern Definitions”
Pattern Activities per user Login frequency
active 10-20 Daily
moderate 5-10 Weekly
inactive 0-3 Monthly
mixed Combination 30% active / 50% moderate / 20% inactive

Examples

Section titled “Examples”
Terminal window
# Create 100 users with a mix of activity levels.
wp bp-stats populate_users --count=100


# Create 50 highly active users.
wp bp-stats populate_users --count=50 --pattern=active

wp bp-stats summary

Section titled “wp bp-stats summary”

Prints a summary of community statistics directly from the database.

Terminal window
wp bp-stats summary

Options

Section titled “Options”
Option Type Default Description
--format=<format> string table table, json, or csv

Examples

Section titled “Examples”
Terminal window
# Default table output.
wp bp-stats summary


# Machine-readable JSON for scripting.
wp bp-stats summary --format=json

Output Columns

Section titled “Output Columns”
  • Total Users
  • Total Groups (if Groups component active)
  • Total Activities (if Activity component active)
  • Activity Log Entries
  • Earliest Log Entry
  • Latest Log Entry

wp bp-stats health_check

Section titled “wp bp-stats health_check”

Verifies that the plugin’s dependencies and database structures are in good shape. Checks BuddyPress activity status, the log table existence, required indexes, plugin settings, and the status of each BuddyPress component.

Terminal window
wp bp-stats health_check

Options

Section titled “Options”
Option Type Default Description
--verbose flag off Show additional detail (row counts, settings values, component status)

Examples

Section titled “Examples”
Terminal window
wp bp-stats health_check
wp bp-stats health_check --verbose

What It Checks

Section titled “What It Checks”
  1. BuddyPress is active
  2. {prefix}_bp_stats_activity_log table exists
  3. Required indexes: the composite indexes BP_Stats_DB_Optimizer::COMPOSITE_INDEXES adds (idx_user_action_date, idx_object_action, idx_topic_date, idx_meta_topic). They are created by the weekly optimizer job, so a brand-new install may report them missing until it has run.
  4. Plugin settings are saved in the database
  5. Status of each BuddyPress component: Activity, Groups, Members, Extended Profiles, Friends, Private Messages

Exit codes: 0 (all pass), 1 (errors), warning message for non-critical issues.

wp bp-stats test

Section titled “wp bp-stats test”

Runs automated tests against the plugin. Useful for verifying an installation after a major WordPress or BuddyPress update.

Terminal window
wp bp-stats test

Options

Section titled “Options”
Option Type Default Description
--component=<component> string all data, permissions, ui, performance, or all

Component Details

Section titled “Component Details”

data - checks the activity log table has entries and has no orphaned rows (log entries for deleted users).

permissions - verifies bp_stats_can_view_user_stats() exists and that at least one administrator can pass the manage_options capability check.

ui - verifies the admin menu item for bp-stats-settings is registered.

performance - times a representative query against the log table; fails if it exceeds 500 ms.

Examples

Section titled “Examples”
Terminal window
# Run all tests.
wp bp-stats test


# Run only permission tests.
wp bp-stats test --component=permissions


# Run performance benchmark only.
wp bp-stats test --component=performance

wp bp-stats cleanup

Section titled “wp bp-stats cleanup”

Deletes test data that was created by generate or populate_users. Asks for confirmation unless --force is passed.

Terminal window
wp bp-stats cleanup

Options

Section titled “Options”
Option Type Default Description
--type=<type> string all users, activities, groups, or all
--force flag off Skip the confirmation prompt

How Cleanup Identifies Test Data

Section titled “How Cleanup Identifies Test Data”
  • Users - searches for bp_stats_test_user user meta key
  • Activities - searches for bp_stats_test_activity activity meta key
  • Groups - searches for bp_stats_test_group group meta key

Only items tagged by the generate commands are removed. Real community data is not touched.

Examples

Section titled “Examples”
Terminal window
# Interactive cleanup (confirms before deleting).
wp bp-stats cleanup


# Delete only test users, no prompt.
wp bp-stats cleanup --type=users --force


# Remove test activities without touching users or groups.
wp bp-stats cleanup --type=activities --force

Typical Workflows

Section titled “Typical Workflows”

Verify a fresh installation

Section titled “Verify a fresh installation”
Terminal window
wp bp-stats health_check --verbose
wp bp-stats summary

Prepare a staging environment with test data

Section titled “Prepare a staging environment with test data”
Terminal window
wp bp-stats generate --comprehensive --cleanup
wp bp-stats summary

Check for data issues after a migration

Section titled “Check for data issues after a migration”
Terminal window
wp bp-stats health_check
wp bp-stats summary --format=json

Notes for Developers

Section titled “Notes for Developers”

The WP-CLI class is located at tests/class-bp-stats-cli-commands.php and is loaded conditionally:

if ( defined( 'WP_CLI' ) && WP_CLI ) {
    $cli_path = plugin_dir_path( __DIR__ ) . 'tests/class-bp-stats-cli-commands.php';
    if ( file_exists( $cli_path ) ) {
        require_once $cli_path;
    }
}

The command group is registered as:

WP_CLI::add_command( 'bp-stats', 'BP_Stats_CLI_Commands' );

These commands are test/development utilities. There are no WP-CLI commands for managing plugin settings or exporting production data. Use the admin UI or direct database queries for production data management.

Section titled “Related Documentation”