WFU WordPress CLI Tool

A comprehensive command-line interface for managing WordPress multisite installations across multiple environments. Automates S3 synchronization, EC2 management, and local development workflows.

📚 Documentation

Tool Introduction - What is wfuwp and how to get started
Built-in Help System - Use wfuwp --help and wfuwp docs --list for complete, current documentation
Developer Documentation - Technical architecture and development guides

Documentation

Developer Guide — Architecture, APIs, and contribution guidelines
Admin Guide — Configuration and usage for WordPress admins
User Guide — Features visible to website visitors

Claude Code Skill: `wfu-maintenance`

A Claude Code skill that drives the wfuwp maintenance command (the wfu.edu down/maintenance page switch) with built-in preflight gates.

Source of truth (version controlled): skills/wfu-maintenance/SKILL.md
Distributed via the WFU internal S3 bucket: s3://wfu-umc-wp-team-internal-docs/skills/wfu-maintenance/SKILL.md (the same private, account-scoped bucket the docs wiki uses; downloading it requires an authenticated WFU AWS session, which the skill needs anyway).
The skill enforces, before any action: wfuwp installed and >= 0.30.0 (auto-updates via npm i -g wfuwp@latest if not), AWS CLI installed, and an authenticated AWS session for the WFU account (841310976649). If a gate fails it stops rather than acting.

Install the skill

You need an authenticated AWS session for the WFU account first (aws sso login). Paste this to Claude Code:

Run aws s3 cp s3://wfu-umc-wp-team-internal-docs/skills/wfu-maintenance/SKILL.md ~/.claude/skills/wfu-maintenance/SKILL.md (create the ~/.claude/skills/wfu-maintenance/ directory first if needed), then confirm the skill is installed.

Or run it directly:

mkdir -p ~/.claude/skills/wfu-maintenance && \
aws s3 cp s3://wfu-umc-wp-team-internal-docs/skills/wfu-maintenance/SKILL.md \
  ~/.claude/skills/wfu-maintenance/SKILL.md

To update the skill later, re-run the same command (it overwrites with the latest published version).

Publishing the skill (maintainers)

The repo is the source of truth; the S3 copy is the distribution mirror. After changing skills/wfu-maintenance/SKILL.md on main, publish it:

aws s3 cp skills/wfu-maintenance/SKILL.md \
  s3://wfu-umc-wp-team-internal-docs/skills/wfu-maintenance/SKILL.md \
  --content-type text/markdown

Database Migration

Note: Database migration functionality has been moved to a dedicated tool: wfu-migrate

Install it with: npm install -g wfu-migrate

See the wfu-migrate documentation for usage.

Installation

Install globally from npm (Recommended)

npm install -g wfuwp

Install from source

git clone <repository-url>
cd wfu-wp-cli
npm install
npm run build
npm link

Prerequisites

Node.js 16.0.0 or higher
AWS CLI installed and configured with appropriate credentials
Access to WFU WordPress S3 buckets

AWS CLI Setup

Make sure you have the AWS CLI installed and configured:

# Install AWS CLI (if not already installed)
# macOS
brew install awscli

# Configure with your credentials
aws configure

Usage

Basic Command Structure

wfuwp <command> [options] [arguments]

Available Commands

Note: For complete command documentation, see the Commands Reference or Quick Reference

`syncs3` - Sync WordPress sites between S3 environments

Synchronizes WordPress site files between different S3 environments.

wfuwp syncs3 <site-id> <from-env> <to-env> [options]

Arguments:

site-id: Numeric site identifier (e.g., 43)
from-env: Source environment (dev, uat, pprd, prod)
to-env: Destination environment (dev, uat, pprd, prod)

Options:

-d, --dry-run: Preview what would be synced without making changes
-f, --force: Skip confirmation prompt
-v, --verbose: Show detailed output including all synced files
-h, --help: Display help for command

Examples:

# Basic sync with confirmation
wfuwp syncs3 43 uat pprd

# Dry run to preview changes
wfuwp syncs3 43 uat pprd --dry-run

# Force sync without confirmation
wfuwp syncs3 43 uat pprd --force

# Show detailed output with all file transfers
wfuwp syncs3 43 uat pprd --verbose

`listips` - List EC2 instance IP addresses

Lists IP addresses of running EC2 instances for a given environment.

wfuwp listips <environment> [options]

Arguments:

environment: Environment name (dev, uat, pprd, prod)

Options:

--private: Show private IP addresses (default behavior)
--public: Show public IP addresses
--json: Output as JSON for scripting
-h, --help: Display help for command

Examples:

# List private IPs (default)
wfuwp listips uat

# List public IPs
wfuwp listips prod --public

# Get JSON output for scripting
wfuwp listips dev --json

`sshaws` - SSH into EC2 instances

SSH into EC2 instances for a given environment with flexible authentication.

wfuwp sshaws <environment> [options]

Arguments:

environment: Environment name (dev, uat, pprd, prod)

Options:

--all: Connect to all instances sequentially (default: first instance only)
--list: List available instances without connecting
--key <path>: Path to SSH private key file (optional)
--user <username>: SSH username (default: ec2-user)
--dry-run: Show what SSH commands would be executed
-h, --help: Display help for command

Examples:

# SSH to first instance (uses system SSH defaults)
wfuwp sshaws uat

# SSH to all instances sequentially
wfuwp sshaws prod --all

# List instances without connecting
wfuwp sshaws dev --list

# Use specific SSH key
wfuwp sshaws pprd --key ~/.ssh/my-aws-key.pem

# Use different username
wfuwp sshaws dev --user ubuntu

# Preview SSH commands
wfuwp sshaws uat --dry-run

`config` - Manage configuration settings

Manage database connection settings and other configuration options. Configuration is stored securely with encrypted passwords.

wfuwp config <subcommand> [arguments]

Subcommands:

# Set configuration values
wfuwp config set <key> <value>

# Get configuration values
wfuwp config get <key>

# List all configuration
wfuwp config list

# Reset all configuration
wfuwp config reset

Multi-Environment Configuration:

environments.dev.host: Development database hostname
environments.dev.user: Development database username
environments.dev.password: Development database password (encrypted)
environments.dev.database: Development database name
environments.uat.host: UAT database hostname
environments.uat.user: UAT database username
environments.uat.password: UAT database password (encrypted)
environments.uat.database: UAT database name
environments.pprd.host: Pre-production database hostname
environments.pprd.user: Pre-production database username
environments.pprd.password: Pre-production database password (encrypted)
environments.pprd.database: Pre-production database name
environments.prod.host: Production database hostname
environments.prod.user: Production database username
environments.prod.password: Production database password (encrypted)
environments.prod.database: Production database name

S3 Configuration (Optional):

s3.bucket: S3 bucket name for backup archival
s3.region: AWS region for S3 bucket (default: us-east-1)
s3.prefix: Prefix for organized S3 storage (default: backups)

Local Backup Configuration (Alternative to S3):

backup.localPath: Local directory for backup storage (default: ~/.wfuwp/backups)

Examples:

# Multi-Environment Setup (Interactive Wizard Recommended)
wfuwp config wizard

# Manual Multi-Environment Configuration
wfuwp config set environments.prod.host prod-db.wfu.edu
wfuwp config set environments.prod.user wp_prod
wfuwp config set environments.prod.password prod_password
wfuwp config set environments.prod.database wp_production

wfuwp config set environments.uat.host uat-db.wfu.edu
wfuwp config set environments.uat.user wp_uat
wfuwp config set environments.uat.password uat_password
wfuwp config set environments.uat.database wp_uat

# S3 Configuration for Backup Archival
wfuwp config set s3.bucket wfu-wp-backups
wfuwp config set s3.region us-east-1
wfuwp config set s3.prefix backups

# Local Backup Alternative
wfuwp config set backup.localPath /path/to/local/backups

# Check current configuration
wfuwp config list

# Verify environment-specific configuration
wfuwp config verify

# Reset all settings
wfuwp config reset

`db` - Database Connection Utilities

Test and verify database connections for all configured environments.

wfuwp db <subcommand>

Subcommands:

test <env> - Test database connection for an environment
list - List all configured database environments

Examples:

# Test production database connection
wfuwp db test prod

# List all configured environments
wfuwp db list

📖 Documentation: See wp-docs/db.md for detailed usage and troubleshooting.

`restore` - Restore Database from Backup

Restore WordPress database from SQL backup files.

wfuwp restore <sql-file> --to <env> [options]

Examples:

# Restore backup to UAT environment
wfuwp restore ./backup.sql --to uat

# Preview restore without making changes
wfuwp restore ./backup.sql --to dev --dry-run

# Restore with increased timeout for large files
wfuwp restore ./large_backup.sql --to pprd --timeout 60

📖 Documentation: See wp-docs/restore.md for detailed usage and recovery workflows.

`clickup` - ClickUp Task Management Integration

Comprehensive ClickUp integration for managing tasks directly from the command line.

wfuwp clickup <subcommand> [options]

Key Features:

Create and manage ClickUp tasks with full metadata support
List and filter tasks with advanced filtering options
Export tasks in CSV, JSON, and Markdown formats
Batch create tasks from text or JSON files
Navigate workspace hierarchies and search across workspaces
Secure encrypted storage of API credentials

Quick Start:

# Configure API token
wfuwp clickup config set token pk_your_api_token

# Create a task
wfuwp clickup create "Fix login bug" --priority high --assignee USER_ID

# List your tasks
wfuwp clickup tasks --my-tasks

# Export tasks to CSV
wfuwp clickup tasks --export csv

📖 Detailed Documentation: See wp-docs/clickup.md for comprehensive usage instructions, batch operations, export formats, and troubleshooting.

`local` - Local Development Environment Management

Complete local development environment management for WFU WordPress sites with DDEV integration, domain management, and automated setup workflows.

✅ All phases complete:

Domain management (modify /etc/hosts)
Environment status and health checks
Automated dependency installation
Environment control (start/stop/restart)
Content management (refresh/reset)
Configuration management

wfuwp local <subcommand> [options]

Available Subcommands:

domain - Manage local development domains (/etc/hosts)
status - Show environment status and health checks
install - Install and setup development dependencies
start - Start local development environment
stop - Stop local development environment
restart - Restart local development environment
refresh - Refresh database from production
reset - Reset entire local environment
config - Configure local development settings

Key Features:

Cross-platform support: macOS, Linux, Windows/WSL
Docker/DDEV integration: Automated container management
Domain management: Separate /etc/hosts markers from DNS spoofing
Environment health: Comprehensive dependency checking
Database refresh: Download from S3 production backups
Interactive setup: Configuration wizard for first-time users

Examples:

# First-time setup workflow
wfuwp local install              # Install Docker, DDEV, dependencies
wfuwp local config wizard        # Configure settings
sudo wfuwp local domain add 43   # Add domain for site 43
wfuwp local install database     # Download production database
wfuwp local start 43             # Start development environment

# Daily development workflow
wfuwp local status               # Check environment health
wfuwp local start 43             # Start site 43
wfuwp local refresh database     # Refresh with latest prod data
wfuwp local stop 43              # Stop when done

# Environment management
wfuwp local domain list          # Show configured domains
wfuwp local reset site43 --deep  # Complete environment reset
wfuwp local install --force      # Reinstall dependencies

Prerequisites:

Docker (will be installed automatically if missing)
DDEV (will be installed automatically if missing)
Sudo access (for domain management only)

System Requirements:

macOS: Homebrew for automated installation
Linux: Native package managers (apt, yum, pacman)
Windows: WSL recommended, manual installation links provided

`maintenance` - Down/Maintenance Page Control

Turn the wfu.edu down/maintenance page on or off per environment. This drives an Application Load Balancer listener rule (not a WordPress plugin); when ON every visitor sees the page except the app loopback and explicit bypass IPs.

wfuwp maintenance <subcommand> --env <dev|uat|pprd|prod>

Available Subcommands:

status - Show ON/OFF, which page, bypass IPs, and verify the live URL
on - Turn the page ON (--page maintenance|down, default maintenance; --allow-me to keep your own access on non-prod)
off - Turn the page OFF, restore prior state, and clear any bypass
allow-me / revoke-me - Add/clear your public IP on the bypass rule (not prod)
init - Provision the standardized ALB rules (dev/uat only)

wfuwp maintenance status --env prod
wfuwp maintenance on --env prod                 # planned work
wfuwp maintenance on --env prod --page down     # unplanned outage
wfuwp maintenance off --env prod

See the Commands Reference for full details and notes.

`uat` - Sleep and Wake the UAT Environment

UAT sleeps when nobody needs it and wakes in a few minutes. While it sleeps, every UAT address shows an "asleep" page; while it wakes, a "waking" page with the walking deacon reloads on its own and lands the visitor where they were going once WordPress is healthy. Waking never changes UAT's code; builds still go through Jenkins.

wfuwp uat status          # ASLEEP, WAKING, AWAKE, or MIXED, with ASG and health detail
wfuwp uat down            # asleep page ON, web and worker ASGs to 0
wfuwp uat up              # waking page ON, ASGs to 1, wait for healthy, page OFF
wfuwp uat up --timeout 30 # wait longer before giving up (minutes, default 25)
wfuwp uat build --base main --with wfu-golinks:feature-wp-1234-x --dry-run
wfuwp uat build --base dev                      # UAT gets each package's dev branch
wfuwp uat build                                 # back to the uat branches

uat build chooses the code UAT builds from: uat (each package's uat branch, the default), dev (each package's dev branch, a shared playground, so not for sign-off), or main (released versions). --with pins one WFU package to a branch and can be repeated. The choice is committed to the app repository's uat branch as uat-build.json, so the baseline is recorded and reproducible, and Jenkins rebuilds UAT from it. Building is always separate from waking; a wake never changes UAT's code.

The branded pages live in uat-pages/ and are served from the UAT CDN at https://uat.wp.cdn.aws.wfu.edu/uat-status/. They share the down page stylesheet at wakealert.wfu.edu/downpage/style.css, so they follow its branding. After editing them, publish with:

for f in asleep.html waking.html; do
  aws s3 cp uat-pages/$f s3://wfu-cer-wordpress-uat-us-east-1/uat-status/$f \
    --content-type "text/html; charset=utf-8" --cache-control "max-age=60"
done
aws s3 cp uat-pages/uat-status.css s3://wfu-cer-wordpress-uat-us-east-1/uat-status/uat-status.css \
  --content-type text/css --cache-control "max-age=60"

The load balancer shows each page in a full-screen frame, the same way the maintenance page is framed. Both frames are ALB fixed responses on the Maintenance Mode rule, so they reuse the maintenance command's saved OFF state; wfuwp maintenance status --env uat reports them as uat-asleep or uat-waking. down refuses to replace a non-UAT maintenance page unless you pass --force.

While UAT sleeps, the three rules ahead of the page (login, the maintenance dashboard, and admin assets) serve the same page, so no UAT address returns a bare 503. The nightly 7 PM sleep puts the page up through the UatWake service in app-serverless-aws-wordpress. Until Information Security changes the UAT template, the weekday 6 AM scale-out still starts the web server behind the asleep page and the worker does not sleep on its own.

Quick Start

New to wfuwp? Start with the Tool Introduction and use the built-in documentation system for complete guidance.

# 1. Install the tool
npm install -g wfuwp

# 2. Check system prerequisites
wfuwp doctor

# 3. Run configuration wizard
wfuwp config wizard

# 4. Verify your setup
wfuwp config verify
wfuwp db list

# 5. Explore built-in documentation
wfuwp --help                    # See all commands
wfuwp docs --list               # Browse documentation topics
wfuwp docs getting-started      # Detailed setup guide

Safety Features

Input Validation

Site IDs must be positive integers
Only valid environment names are accepted
Source and destination environments cannot be the same

Confirmation Prompts

Interactive confirmation before executing sync operations
Use --force flag to bypass confirmations in automated scripts

Dry Run Mode

Use --dry-run to preview what files would be synced
No actual changes are made in dry-run mode

Secure Configuration Storage

Database passwords are encrypted when stored locally
Configuration files are stored in user's home directory (~/.wfuwp/config.json)

AWS CLI Verification

Checks if AWS CLI is installed and accessible
Provides helpful error messages if prerequisites are missing

Troubleshooting

Common Issues

"AWS CLI is not installed or not in PATH"

Install AWS CLI: https://aws.amazon.com/cli/
Ensure it's in your system PATH

"Site ID must be a positive integer"

Ensure you're using a numeric site ID (e.g., 43, not "abc")

"Invalid source/destination environment"

Use only valid environment names: dev, uat, pprd, prod

"Source and destination environments cannot be the same"

Ensure you're specifying different environments for source and destination

"Database configuration incomplete"

Set up database connection using wfuwp config set commands
Ensure all required fields are configured: host, user, password, name

Getting Help

# General help
wfuwp --help

# Command-specific help
wfuwp syncs3 --help
wfuwp config --help

# Display version
wfuwp --version

Development

Building from Source

git clone <repository-url>
cd wfu-wp-cli
npm install
npm run build

Development Scripts

npm run build      # Compile TypeScript
npm run dev        # Run with ts-node for development
npm run test       # Run tests
npm run lint       # Run ESLint
npm run format     # Format code with Prettier

Project Structure

wfu-wp-cli/
├── src/
│   ├── commands/
│   │   ├── syncs3.ts     # S3 sync command implementation
│   │   ├── listips.ts    # EC2 IP listing command
│   │   ├── sshaws.ts     # SSH connection command
│   │   ├── removehostkey.ts # SSH host key removal command
│   │   └── config.ts     # Configuration management command
│   ├── utils/
│   │   └── config.ts     # Configuration storage utilities
│   └── index.ts          # Main CLI entry point
├── bin/
│   └── wfuwp            # Binary wrapper
├── dist/                # Compiled JavaScript (generated)
├── tests/               # Test files
├── docs/                # Additional documentation
└── package.json         # Package configuration

Contributing

Fork the repository
Create a feature branch: git checkout -b feature-name
Make your changes
Run tests: npm test
Run linting: npm run lint
Commit your changes: git commit -m "feat: add new feature"
Push to the branch: git push origin feature-name
Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

Check the troubleshooting section above
Search existing issues in the repository
Create a new issue with detailed information about the problem

Name		Name	Last commit message	Last commit date
.claude		.claude
.github/workflows		.github/workflows
bin		bin
docs		docs
documentation		documentation
project-planning		project-planning
scripts		scripts
skills/wfu-maintenance		skills/wfu-maintenance
src		src
tests		tests
uat-pages		uat-pages
wp-cli-env		wp-cli-env
wp-docs		wp-docs
.eslintrc.js		.eslintrc.js
.gitignore		.gitignore
.npmignore		.npmignore
.prettierrc		.prettierrc
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
Dockerfile.test		Dockerfile.test
LICENSE		LICENSE
PUBLISH_INSTRUCTIONS.md		PUBLISH_INSTRUCTIONS.md
README.md		README.md
RECOMMENDATIONS.md		RECOMMENDATIONS.md
TODO.md		TODO.md
UPDATED_RECOMMENDATIONS.md		UPDATED_RECOMMENDATIONS.md
docker-compose.test.yml		docker-compose.test.yml
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
test-config-setup.sh		test-config-setup.sh
test-install.sh		test-install.sh
test-user-experience.sh		test-user-experience.sh
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation

WFU WordPress CLI Tool

📚 Documentation

Documentation

Claude Code Skill: wfu-maintenance

Install the skill

Publishing the skill (maintainers)

Database Migration

Installation

Install globally from npm (Recommended)

Install from source

Prerequisites

AWS CLI Setup

Usage

Basic Command Structure

Available Commands

syncs3 - Sync WordPress sites between S3 environments

listips - List EC2 instance IP addresses

sshaws - SSH into EC2 instances

config - Manage configuration settings

db - Database Connection Utilities

restore - Restore Database from Backup

clickup - ClickUp Task Management Integration

local - Local Development Environment Management

maintenance - Down/Maintenance Page Control

uat - Sleep and Wake the UAT Environment

Quick Start

Safety Features

Input Validation

Confirmation Prompts

Dry Run Mode

Secure Configuration Storage

AWS CLI Verification

Troubleshooting

Common Issues

Getting Help

Development

Building from Source

Development Scripts

Project Structure

Contributing

License

Support

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Claude Code Skill: `wfu-maintenance`

`syncs3` - Sync WordPress sites between S3 environments

`listips` - List EC2 instance IP addresses

`sshaws` - SSH into EC2 instances

`config` - Manage configuration settings

`db` - Database Connection Utilities

`restore` - Restore Database from Backup

`clickup` - ClickUp Task Management Integration

`local` - Local Development Environment Management

`maintenance` - Down/Maintenance Page Control

`uat` - Sleep and Wake the UAT Environment