Better Search Pro CLI Overview

Better Search Pro CLI (BSP-CLI) was introduced in Better Search Pro v4.3.0, allowing you to manage search operations without touching the admin dashboard. If you’re running large-scale WordPress installations or automating deployments, these commands handle everything from cache warming to database maintenance.

About WP-CLI

WP-CLI is a powerful set of command-line tools for managing WordPress installations. You can update plugins, configure multisite installations, and much more, all without using a web browser. For more information, visit the official WP-CLI websiteOpens in a new window.

Getting Started with BSP-CLI

To begin using BSP-CLI, ensure that WP-CLI is installed and that you are running Better Search Pro 4.2.0 or later. The CLI commands are accessed through the wp bsearch command. For a complete list of available commands, type wp bsearch in your command-line interface.

Command Structure

All commands use the wp bsearch namespace:

wp bsearch <command> <subcommand> [options]

Available Commands

Run search queries directly from the command line.

wp bsearch search "search term"

Options

  • --limit=<number> — Number of results (default: 10)
  • --post-type=<types> — Comma-separated post types (default: post)
  • --[no-]use-fulltext — Force FULLTEXT search ON or OFF
  • --[no-]boolean-mode — Use boolean mode for FULLTEXT ON or OFF
  • --format=<format> — Output format: table, json, csv (default: table)
  • --verbose — Show detailed output

Examples

# Search for "WordPress" and show 20 results
wp bsearch search "WordPress" --limit=20

# Search across multiple post types
wp bsearch search "tutorial" --post-type=post,page

# Get results in JSON format
wp bsearch search "mysql" --format=json

Status

Show comprehensive plugin status and configuration.

wp bsearch status

Options:

  • --format=<format> — Output format: table, json, csv
  • --verbose — Show detailed information
  • --network — Show status for all network sites

Cache

Manage the search results cache.

Clear Cache

wp bsearch cache clear

Options:

  • --network — Clear cache for all sites in the network
  • --force — Skip confirmation
  • --dry-run — Preview without making changes
  • --verbose — Show detailed output

Warm Cache

Pre-generate search results for your most popular queries.

wp bsearch cache warm

Options:

  • --limit=<number> — Number of top searches to warm (default: 50)
  • --batch-size=<size> — Batch size for processing (default: 100)
  • --dry-run — Preview without making changes
  • --force — Force cache warming even if cache exists

Cache Status

wp bsearch cache status

Options:

  • --format=<format> — Output format: table, json, csv

Database (db)

Manage database tables and FULLTEXT indexes.

Database Status

wp bsearch db status

Options:

  • --format=<format> — Output format: table, json, csv
  • --network — Show status for all network sites
  • --blog-id=<id> — Specific blog ID (multisite only)

Create Tables

Creates the Better Search tables used for tracking. These are not the custom table (ECSI) tables.

wp bsearch db create-tables

Options:

  • --dry-run — Preview without creating
  • --force — Force creation even if tables exist

Recreate Tables

wp bsearch db recreate-tables

Options:

  • --backup — Create backup tables (default: true)
  • --no-backup — Skip backup creation
  • --force — Skip confirmation
  • --dry-run — Preview without making changes

Manage FULLTEXT Indexes

Check status:

wp bsearch db indexes status

Create indexes:

wp bsearch db indexes create

Delete indexes:

wp bsearch db indexes delete --force

Recreate indexes:

wp bsearch db indexes recreate

Statistics (stats)

View and manage search query statistics.

View Statistics

wp bsearch stats view

Options:

  • --limit=<number> — Number of entries (default: 20)
  • --table=<table> — Table to query: overall, daily (default: overall)
  • --orderby=<field> — Order by: searchvar, cntaccess, dp_date (default: cntaccess)
  • --order=<direction> — Sort order: asc, desc (default: desc)
  • --format=<format> — Output format: table, json, csv

Top Searches

wp bsearch stats top --limit=50

Clear Statistics

wp bsearch stats clear --force

Options:

  • --before=<date> — Clear entries before date (YYYY-MM-DD)
  • --table=<table> — Which table: overall, daily, all (default: all)
  • --force — Skip confirmation
  • --dry-run — Preview without clearing

Export Statistics

wp bsearch stats export

Options:

  • --file=<path> — Export file path (default: bsearch-stats-{timestamp}.csv)
  • --table=<table> — Table to export: overall, daily
  • --limit=<number> — Maximum entries to export (default: all)

Settings

Manage plugin settings from the command line.

Export Settings

wp bsearch settings export

Options:

  • --file=<path> — Export file path (default: bsearch-settings-{timestamp}.json)

Import Settings

wp bsearch settings import settings.json

Options:

  • --merge — Merge with existing settings instead of replacing
  • --dry-run — Preview without importing

Get Setting

wp bsearch settings get seamless

Options:

  • --format=<format> — Output format: value, table, json, csv (default: value)

Set Setting

wp bsearch settings set seamless true --type=bool

Options:

  • --type=<type> — Value type: string, int, bool, array (default: auto-detect)

Custom Tables (ECSI)

Manage custom search index tables. Learn more about ECSI.

Create Custom Tables

wp bsearch ecsi create

Options:

  • --dry-run — Preview without creating
  • --verbose — Show detailed output

Drop Custom Tables

wp bsearch ecsi drop --force

Tables Status

wp bsearch ecsi status

Options:

  • --format=<format> — Output format: table, json, csv
  • --network — Show status for all network sites

Reindex Posts

wp bsearch ecsi reindex

Options:

  • --force — Force reindex (truncate tables first)
  • --batch-size=<size> — Batch size for processing (default: 100)
  • --post-type=<types> — Comma-separated post types (default: all public types)
  • --dry-run — Preview without reindexing

Manage Custom Table Indexes

Create indexes:

wp bsearch ecsi indexes create

Delete indexes:

wp bsearch ecsi indexes delete --force

Recreate indexes:

wp bsearch ecsi indexes recreate

Check status:

wp bsearch ecsi indexes status

Stopwords

Manage search stopwords. These are words excluded from search queries.

Add Stopwords

wp bsearch stopwords add the and a an

Options:

  • --network — Add stopwords for all sites in the network
  • --blog-id=<id> — Specific blog ID (multisite only)

Remove Stopwords

wp bsearch stopwords remove the and

Options:

  • --network — Remove stopwords for all sites in the network
  • --blog-id=<id> — Specific blog ID (multisite only)

List Stopwords

wp bsearch stopwords list

Options:

  • --format=<format> — Output format: table, json, csv
  • --network — List stopwords for all sites in the network
  • --blog-id=<id> — Specific blog ID (multisite only)

Clear Stopwords

wp bsearch stopwords clear

Options:

  • --force — Skip confirmation prompt
  • --network — Clear stopwords for all sites in the network
  • --blog-id=<id> — Specific blog ID (multisite only)

Common Workflows

Initial Setup

# Create database tables
wp bsearch db create-tables

# Create FULLTEXT indexes
wp bsearch db indexes create

# Verify setup
wp bsearch status

Multisite Setup

# Check status for all sites
wp bsearch db status --network

# Clear cache across the network
wp bsearch cache clear --network --force

Performance Optimisation

# Warm cache for top 100 searches
wp bsearch cache warm --limit=100

# Enable custom tables
wp bsearch settings set use_custom_table true --type=bool

# Reindex posts into custom tables
wp bsearch tables reindex

Maintenance

# Clear old statistics
wp bsearch stats clear --before=2024-01-01

# Recreate FULLTEXT indexes
wp bsearch db indexes recreate

# Clear and warm cache
wp bsearch cache clear --force
wp bsearch cache warm

Backup and Migration

# Export settings
wp bsearch settings export --file=backup-settings.json

# Export statistics
wp bsearch stats export --file=backup-stats.csv

# Import on new site
wp bsearch settings import backup-settings.json

Multisite Support

Most commands work across multisite networks. Commands that use multisite iteration (such as cache clear, db status, tables status, stats view, and stopwords) support these options:

  • --network — Execute across all sites in the network
  • --blog-id=<id> — Target specific site by ID
  • --url=<url> — Target specific site by URL

Commands like db create-tables, db recreate-tables, cache warm, and tables reindex run against the current site only. Use WP-CLI’s global --url parameter to target a specific site.

Multisite Examples

# Clear cache network-wide
wp bsearch cache clear --network

# Check status for specific site
wp bsearch status --blog-id=2

# Reindex specific site
wp bsearch tables reindex --url=https://example.com

Output Formats

Most commands support three output formats:

  • table — Human-readable table (default)
  • json — JSON format for scripting
  • csv — CSV format for spreadsheets

Format Examples

# JSON output for scripting
wp bsearch stats top --format=json | jq '.[] | .["Search Term"]'

# CSV output for Excel
wp bsearch stats view --format=csv > statistics.csv

Error Handling

Commands use standard WP-CLI exit codes:

  • 0 — Success
  • 1 — Error

Common Errors

Plugin not active

Error: Better Search plugin is not active.

Activate Better Search Pro first.

Database connection failed

Error: Database connection failed.

Check your database credentials in wp-config.php.

Operation in progress

Error: Operation 'reindex' already in progress. Use --force to override.

Wait for the current operation to finish or use --force to override the lock file.

Best Practices

Use Dry Run

I always preview destructive operations first:

wp bsearch stats clear --dry-run
wp bsearch tables reindex --dry-run

Batch Processing

On large sites, reduce batch sizes to avoid memory issues:

wp bsearch tables reindex --batch-size=50

Lock Files

Long-running operations create lock files in your temp directory to prevent concurrent execution. These clean up automatically on completion or error.

Verbose Mode

Use --verbose when troubleshooting:

wp bsearch cache warm --verbose

Scripting Examples

Daily Cache Warm

#!/bin/bash
# warm-cache.sh
wp bsearch cache warm --limit=100 --force

Weekly Statistics Export

#!/bin/bash
# export-stats.sh
DATE=$(date +%Y-%m-%d)
wp bsearch stats export --file="stats-${DATE}.csv"

Multisite Maintenance

#!/bin/bash
# multisite-maintenance.sh
wp bsearch cache clear --network --force
wp bsearch stats clear --before=$(date -v-90d +%Y-%m-%d) --force
# Note: Use date -d '90 days ago' on GNU/Linux instead of -v-90d.

Troubleshooting

Check Plugin Status

wp bsearch status --verbose

Verify Database Tables

wp bsearch db status

Test Search Functionality

wp bsearch search "test" --verbose

Clear All Caches

wp bsearch cache clear --force
wp cache flush

Get Better Search Pro

Download WebberZone Knowledge Base plugin for WordPressDownload Better Search Free Download WebberZone Knowledge Base plugin for WordPressBuy Better Search Pro

Was this article helpful?

Related Articles

Leave a Reply

Your email address will not be published. Required fields are marked *