docs: Add WP-CLI helper script and comprehensive usage guide

WP_CLI_GUIDE.md

@@ -0,0 +1,327 @@
+# WP-CLI Usage Guide for WooNooW with Local WP
+
+## ✅ Installation Complete
+
+WP-CLI has been successfully installed via Homebrew:
+- **Version:** 2.12.0
+- **Location:** `/usr/local/bin/wp`
+- **Installed:** November 5, 2025
+
+---
+
+## 🚀 Quick Start
+
+### Basic Usage
+
+```bash
+# From plugin directory
+wp [command] --path="/Users/dwindown/Local Sites/woonoow/app/public"
+
+# Or use the helper script
+./wp-cli-helper.sh [command]
+```
+
+### Common Commands for WooNooW Development
+
+#### 1. Flush Navigation Cache
+```bash
+# Delete navigation tree cache (forces rebuild)
+wp option delete wnw_nav_tree --path="/Users/dwindown/Local Sites/woonoow/app/public"
+
+# Or with helper
+./wp-cli-helper.sh option delete wnw_nav_tree
+```
+
+#### 2. Check Plugin Status
+```bash
+# List all plugins
+wp plugin list --path="/Users/dwindown/Local Sites/woonoow/app/public"
+
+# Check WooNooW status
+wp plugin status woonoow --path="/Users/dwindown/Local Sites/woonoow/app/public"
+```
+
+#### 3. Activate/Deactivate Plugin
+```bash
+# Deactivate
+wp plugin deactivate woonoow --path="/Users/dwindown/Local Sites/woonoow/app/public"
+
+# Activate
+wp plugin activate woonoow --path="/Users/dwindown/Local Sites/woonoow/app/public"
+```
+
+#### 4. Clear All Caches
+```bash
+# Flush object cache
+wp cache flush --path="/Users/dwindown/Local Sites/woonoow/app/public"
+
+# Flush rewrite rules
+wp rewrite flush --path="/Users/dwindown/Local Sites/woonoow/app/public"
+
+# Clear transients
+wp transient delete --all --path="/Users/dwindown/Local Sites/woonoow/app/public"
+```
+
+#### 5. Database Operations
+```bash
+# Export database
+wp db export backup.sql --path="/Users/dwindown/Local Sites/woonoow/app/public"
+
+# Search and replace (useful for URL changes)
+wp search-replace 'old-url.com' 'new-url.com' --path="/Users/dwindown/Local Sites/woonoow/app/public"
+
+# Optimize database
+wp db optimize --path="/Users/dwindown/Local Sites/woonoow/app/public"
+```
+
+#### 6. WooCommerce Specific
+```bash
+# Update WooCommerce database
+wp wc update --path="/Users/dwindown/Local Sites/woonoow/app/public"
+
+# List WooCommerce orders
+wp wc shop_order list --path="/Users/dwindown/Local Sites/woonoow/app/public"
+
+# Clear WooCommerce cache
+wp wc tool run clear_transients --path="/Users/dwindown/Local Sites/woonoow/app/public"
+```
+
+---
+
+## 🛠️ Helper Script
+
+A helper script has been created: `wp-cli-helper.sh`
+
+**Usage:**
+```bash
+# Make it executable (already done)
+chmod +x wp-cli-helper.sh
+
+# Use it
+./wp-cli-helper.sh option delete wnw_nav_tree
+./wp-cli-helper.sh plugin list
+./wp-cli-helper.sh cache flush
+```
+
+**Add to your shell profile for global access:**
+```bash
+# Add to ~/.zshrc or ~/.bash_profile
+alias wplocal='wp --path="/Users/dwindown/Local Sites/woonoow/app/public"'
+
+# Then use anywhere:
+wplocal option delete wnw_nav_tree
+wplocal plugin list
+```
+
+---
+
+## 🔧 Troubleshooting
+
+### Database Connection Error
+
+If you see: `Error establishing a database connection`
+
+**Solution 1: Start Local WP Site**
+Make sure your Local WP site is running:
+1. Open Local WP app
+2. Start the "woonoow" site
+3. Wait for MySQL to start
+4. Try WP-CLI command again
+
+**Solution 2: Use wp-config.php Path**
+WP-CLI reads database credentials from `wp-config.php`. Ensure Local WP site is running so the database is accessible.
+
+**Solution 3: Check MySQL Socket**
+Local WP uses a custom MySQL socket. The site must be running for WP-CLI to connect.
+
+---
+
+## 📚 Useful WP-CLI Commands for Development
+
+### Plugin Development
+```bash
+# Check for PHP errors
+wplocal eval 'error_reporting(E_ALL); ini_set("display_errors", 1);'
+
+# List all options (filter by prefix)
+wplocal option list --search="wnw_*"
+
+# Get specific option
+wplocal option get wnw_nav_tree
+
+# Update option
+wplocal option update wnw_nav_tree '{"version":"1.0.0"}'
+
+# Delete option
+wplocal option delete wnw_nav_tree
+```
+
+### User Management
+```bash
+# List users
+wplocal user list
+
+# Create admin user
+wplocal user create testadmin test@example.com --role=administrator --user_pass=password123
+
+# Update user role
+wplocal user set-role 1 administrator
+```
+
+### Post/Page Management
+```bash
+# List posts
+wplocal post list
+
+# Create test post
+wplocal post create --post_type=post --post_title="Test Post" --post_status=publish
+
+# Delete all posts
+wplocal post delete $(wplocal post list --post_type=post --format=ids)
+```
+
+### Theme/Plugin Info
+```bash
+# List themes
+wplocal theme list
+
+# Get site info
+wplocal core version
+wplocal core check-update
+
+# Get PHP info
+wplocal cli info
+```
+
+---
+
+## 🎯 WooNooW Specific Commands
+
+### Navigation Cache Management
+```bash
+# Delete navigation cache (forces rebuild on next page load)
+wplocal option delete wnw_nav_tree
+
+# View current navigation tree
+wplocal option get wnw_nav_tree --format=json | jq .
+
+# Check navigation version
+wplocal option get wnw_nav_tree --format=json | jq .version
+```
+
+### Plugin Options
+```bash
+# List all WooNooW options
+wplocal option list --search="wnw_*" --format=table
+
+# List all WooNooW options (alternative)
+wplocal option list --search="woonoow_*" --format=table
+
+# Export all WooNooW settings
+wplocal option list --search="wnw_*" --format=json > woonoow-settings-backup.json
+```
+
+### Development Workflow
+```bash
+# 1. Make code changes
+# 2. Flush caches
+wplocal cache flush
+wplocal option delete wnw_nav_tree
+
+# 3. Rebuild assets (from plugin directory)
+cd /Users/dwindown/Local\ Sites/woonoow/app/public/wp-content/plugins/woonoow/admin-spa
+npm run build
+
+# 4. Test in browser
+# 5. Check for errors
+wplocal plugin status woonoow
+```
+
+---
+
+## 📖 Learn More
+
+### Official Documentation
+- **WP-CLI Handbook:** https://make.wordpress.org/cli/handbook/
+- **Command Reference:** https://developer.wordpress.org/cli/commands/
+- **WooCommerce CLI:** https://github.com/woocommerce/woocommerce/wiki/WC-CLI-Overview
+
+### Quick Reference
+```bash
+# Get help for any command
+wp help [command]
+wp help option
+wp help plugin
+
+# List all available commands
+wp cli cmd-dump
+
+# Check WP-CLI version
+wp --version
+
+# Update WP-CLI
+brew upgrade wp-cli
+```
+
+---
+
+## 💡 Pro Tips
+
+### 1. Use Aliases
+Add to `~/.zshrc`:
+```bash
+alias wplocal='wp --path="/Users/dwindown/Local Sites/woonoow/app/public"'
+alias wpflush='wplocal cache flush && wplocal option delete wnw_nav_tree'
+alias wpplugins='wplocal plugin list'
+```
+
+### 2. JSON Output
+Most commands support `--format=json` for parsing:
+```bash
+wplocal option get wnw_nav_tree --format=json | jq .
+wplocal plugin list --format=json | jq '.[] | select(.name=="woonoow")'
+```
+
+### 3. Batch Operations
+```bash
+# Deactivate all plugins except WooCommerce and WooNooW
+wplocal plugin list --status=active --field=name | grep -v -E '(woocommerce|woonoow)' | xargs wplocal plugin deactivate
+```
+
+### 4. Script Integration
+```bash
+#!/bin/bash
+# Deploy script example
+echo "Deploying WooNooW..."
+wplocal plugin deactivate woonoow
+cd admin-spa && npm run build
+wplocal plugin activate woonoow
+wplocal cache flush
+wplocal option delete wnw_nav_tree
+echo "Deployment complete!"
+```
+
+---
+
+## ✅ Installation Summary
+
+**Installed via Homebrew:**
+- WP-CLI 2.12.0
+- PHP 8.4.14 (dependency)
+- All required dependencies
+
+**Helper Files Created:**
+- `wp-cli-helper.sh` - Quick command wrapper
+- `WP_CLI_GUIDE.md` - This guide
+
+**Next Steps:**
+1. Ensure Local WP site is running
+2. Test: `./wp-cli-helper.sh option delete wnw_nav_tree`
+3. Reload wp-admin to see settings submenu
+4. Add shell aliases for convenience
+
+---
+
+**Last Updated:** November 5, 2025  
+**WP-CLI Version:** 2.12.0  
+**Status:** ✅ Ready to Use

wp-cli-helper.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+# WP-CLI Helper for Local WP
+# Usage: ./wp-cli-helper.sh [wp command]
+# Example: ./wp-cli-helper.sh option delete wnw_nav_tree
+
+# Local WP WordPress path
+WP_PATH="/Users/dwindown/Local Sites/woonoow/app/public"
+
+# Run WP-CLI with correct path
+wp "$@" --path="$WP_PATH"