npm package: @perlatsp/wpm
Description: A comprehensive command-line interface tool for managing WordPress installations, providing functionality for updates, backups, security audits, and system maintenance.
Author: Perlat Kociaj
Latest version: 0.9.10

# WordPress Maintenance CLI

A comprehensive command-line interface tool for managing WordPress installations, providing functionality for updates, backups, security audits, health checks, and system maintenance.

## Features

- 🔄 **Plugin Updates**: Interactive plugin management with version tracking and changelog generation
- 💾 **Database Operations**: Backup, restore, and cleanup database operations
- 🛡️ **Security Audits**: Comprehensive security scanning and vulnerability detection
- 🏥 **Health Checks**: Site availability and endpoint testing
- 📊 **System Information**: Detailed WordPress installation insights
- 📝 **Changelog Generation**: Automatic update tracking with file change details
- 🔧 **Git Integration**: Optional automatic commits for changes

## Prerequisites

- Node.js (v18 or higher)
- WordPress installation
- WP-CLI installed and accessible globally
- Git (optional, for commit functionality)

## Installation

```bash
npm install -g @perlatsp/wpm
```

## Quick Start

1. **Navigate to your WordPress directory**:
   ```bash
   cd /path/to/your/wordpress
   ```

2. **Run the tool**:
   ```bash
   wpm
   ```

3. **Choose your operation** from the interactive menu

## Commands

### Update Plugins (`update`)

Manage WordPress plugin updates interactively with detailed changelog generation.

```bash
wpm update
```

**Features:**
- Select individual plugins or update all at once
- View current and available versions for each plugin
- Distinguish between active and inactive plugins
- Optional automatic Git commits for updates
- Health checks after updates
- Automatic changelog generation with file change tracking
- Detailed update progress and error reporting

**Example Output:**
```bash
$ wpm update

? What would you like to do? Select Plugins
✔ Found 3 plugins with available updates
  • Wordfence Security (wordfence) (7.10.2 → 7.10.3)
  • Advanced Custom Fields PRO (advanced-custom-fields-pro) (6.0.7 → 6.1.0)
  • WooCommerce (woocommerce) (7.9.0 → 8.0.0)

? Select plugins to update: [✓] Wordfence Security, [✓] WooCommerce
? Are you sure you want to update the following plugins:
- wordfence: 7.10.2 → 7.10.3
- woocommerce: 7.9.0 → 8.0.0
? Yes
? Would you like to perform health checks after each plugin update? Yes
? Do you want to commit these changes? Yes
? Would you like to create/update update-changelog.md with plugin update details? Yes

Updating wordfence...
✅ Update successful
✅ Health check passed
Created commit for Wordfence Security update

Updating woocommerce...
✅ Update successful
✅ Health check passed
Created commit for WooCommerce update

✅ Changelog written to: /path/to/wordpress/update-changelog.md
```

## Generated Changelog Example:

### 2024-01-15
#### 2 plugin(s) changed

<details><summary>Wordfence Security updated from version 7.10.2 to version 7.10.3.</summary>

- <span style="color:orange">15 Files Updated</span>
- <span style="color:green">2 files created</span>
- <span style="color:red">1 Files removed</span>
</details>

<details><summary>WooCommerce updated from version 7.9.0 to version 8.0.0.</summary>

- <span style="color:orange">45 Files Updated</span>
- <span style="color:green">8 files created</span>
- <span style="color:red">3 Files removed</span>
</details>


### Health Check (`healthcheck`)

Perform site health checks to verify your WordPress installation is accessible and functioning properly.

```bash
wpm healthcheck
```

**Features:**
- Tests main site URL accessibility
- Verifies WordPress admin area access
- Checks REST API endpoint functionality
- Provides detailed status codes and error messages
- Quick site health overview

**Example Output:**
```bash
$ wpm healthcheck

Performing site health check...
Checking https://example.com ...
✅ OK (200)
Checking https://example.com/wp-admin/ ...
✅ OK (200)
Checking https://example.com/wp-json/ ...
✅ OK (200)

✅ All health checks passed!
```

### Security Audit (`security`)

Perform comprehensive security checks on your WordPress installation.

```bash
wpm security
```

**Features:**
- ✅ File permissions audit
- ✅ WordPress core integrity verification
- ✅ Plugin and theme security checks
- ✅ User security analysis
- ✅ SSL configuration verification
- ✅ Database security assessment
- ✅ PHP version security check
- ✅ Security headers verification
- ✅ Suspicious file detection
- ✅ WordPress configuration analysis
- ✅ Detailed reporting with critical issues, warnings, and recommendations
- ✅ Automatic security report generation (`security-report.md`)

**Example Output:**
```bash
$ wpm security

🔒 Running WordPress Security Checks...

📁 Checking file permissions...
⚠️  wp-config.php permissions are not secure: 644
   Recommended: 600

🔄 Checking WordPress version...
✅ WordPress is up to date

📊 Security Scan Summary
❌ Critical Issues:
 • wp-config.php has unsafe permissions: 644 (should be 600)
 • Core files have been modified

⚠️  Warnings:
 • No known security plugins detected
 • 3 plugins need updates

📝 Recommendations:
 • Change wp-config.php permissions to 600
 • Install a security plugin (e.g., Wordfence)
 • Update outdated plugins

✅ Security report written to: /homedir/example_com_security-report.md
```

### Database Operations (`db`)

Manage WordPress database operations with safety features.

```bash
wpm db
```

**Features:**
- Database cleanup with optional backup
- Database export with automatic naming
- Database import with file selection interface
- Search and replace functionality with dry-run capability
- File size and date information
- Verification of changes

**Example Usage:**
```bash
$ wpm db

? What would you like to do? Database Export
? Enter a custom name for the backup (optional): my-backup
✅ Database exported to: /path/to/wordpress/backups/2024-01-15/db-my-backup-2024-01-15-14-30-22.sql.gz
```

### Backup (`backup`)

Create comprehensive backups of your WordPress installation.

```bash
wpm backup
```

**Features:**
- Selective backup options (database, files, or complete)
- File backup options (entire site, themes, plugins, uploads)
- Automatic compression
- Organized backup structure by date
- Automatic backup location selection
- Error handling and cleanup for failed backups

**Example Usage:**
```bash
$ wpm backup

? What would you like to backup? Complete Backup
? Select backup location: /home/user/backups
✅ Backup completed successfully!
📁 Database: /home/user/backups/2024-01-15/db-2024-01-15-14-30-22.sql.gz
📁 Files: /home/user/backups/2024-01-15/files-2024-01-15-14-30-22.tar.gz
```

### System Information (`info`)

Display detailed information about your WordPress installation.

```bash
wpm info
```

**Features:**
- Core WordPress information
- Environment details
- Plugin status and counts
- Theme information
- User statistics
- Media library details
- System configuration
- PHP settings
- Database details
- Site accessibility check

**Example Output:**
```bash
$ wpm info

📊 WordPress Information
Version: 6.4.2
Site URL: https://example.com
Home URL: https://example.com
Database Size: 45.2 MB
Upload Directory: /path/to/wordpress/wp-content/uploads

🔧 System Information
PHP Version: 8.1.15
MySQL Version: 8.0.35
Web Server: nginx/1.24.0
Memory Limit: 256M

📦 Plugin Information
Total Plugins: 25
Active Plugins: 18
Inactive Plugins: 7
Plugins with Updates: 3
```

## Configuration

The tool automatically detects your WordPress installation and creates configuration files as needed. Configuration is stored in:

- **Global Config**: `~/.wpmce-config.json`
- **Site Config**: `{wordpress-root}/.wpm-config.json`

## Directory Structure

Backups, logs, and reports are organized in the following structure:

```
/path/to/wordpress/
├── backups/
│   └── YYYY-MM-DD/
│       ├── db-YYYY-MM-DD-HH-mm-ss.sql.gz
│       └── files-YYYY-MM-DD-HH-mm-ss.tar.gz
├── update-changelog.md
└── security-report.md
```
```
/home/dir
   └── example_com_security-report.md
```



## Safety Features

- **Automatic backups** before critical operations
- **Health checks** after updates
- **Dry-run capabilities** for destructive operations
- **Confirmation prompts** for all major actions
- **Error recovery** with detailed error messages
- **Rollback capabilities** through Git integration

## Requirements

### System Requirements
- **Node.js**: v18 or higher
- **PHP**: 7.4 or higher (for WordPress)
- **MySQL/MariaDB**: 5.7 or higher
- **Git**: 2.0 or higher (optional, for commit functionality)

### WordPress Requirements
- **WordPress**: 5.0 or higher
- **WP-CLI**: Latest version (will be installed automatically if missing)
- **File permissions**: Read/write access to WordPress directory

## Troubleshooting

### Common Issues

**1. WP-CLI not found**
```bash
# The tool will offer to install WP-CLI automatically
# Or install manually:
curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar
chmod +x wp-cli.phar
sudo mv wp-cli.phar /usr/local/bin/wp
```

**2. Permission denied errors**
```bash
# Ensure proper file permissions
chmod 755 /path/to/wordpress
chmod 644 /path/to/wordpress/wp-config.php
```

**3. Database connection issues**
```bash
# Verify wp-config.php settings
# Check database credentials
# Ensure database server is running
```

### Getting Help

- Check the logs in `maintenance-logs/` directory
- Verify WordPress installation with `wpm info`
- Run health checks with `wpm healthcheck`
- Review security report with `wpm security`

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

### Development Setup

```bash
git clone https://github.com/your-repo/wordpress-maintenance-cli.git
cd wordpress-maintenance-cli
npm install
npm link
```

### Testing

```bash
npm test
```

## License

[MIT](LICENSE)

## Support

For support, please:

1. Check the troubleshooting section above
2. Review the logs in `maintenance-logs/` directory
3. Open an issue on GitHub with:
   - Your WordPress version
   - Node.js version
   - Error messages from logs
   - Steps to reproduce the issue

---



⚠️ **IMPORTANT DISCLAIMER - USE AT YOUR OWN RISK** ⚠️

**This tool is provided "as is" without any warranties or guarantees. By using this software, you acknowledge and agree that:**

- You use this tool entirely at your own risk
- The author(s) take no responsibility for any damage, data loss, or issues that may occur
- You should **always backup your WordPress site** before running any maintenance operations
- This tool performs direct operations on your WordPress database and files
- **Test thoroughly on a staging environment** before using on production sites
- You are responsible for verifying all operations and their results
- The author(s) are not liable for any direct, indirect, incidental, or consequential damages
- The S3 Bucket access key and access secret will be saved in the configuration file {home directory}/.wpmce-config.json please, If you do not feel comfortable with this, please do NOT use the tool!
- This tool was built for personal use initially, but publishing it in case it is usefull for someone else.

**NEVER use this tool on production sites without proper testing and backups. WordPress maintenance operations can be irreversible.**

---