---
description: This skill should be used when the user asks to "set up WordPress", "configure WooCommerce API", "connect to my WordPress site", "generate API keys", "create Application Password", mentions "WordPress authentication", "WooCommerce credentials", or needs help with initial WordPress/WooCommerce plugin configuration and credential setup.
---

# WordPress & WooCommerce Setup Configuration

Comprehensive guide for setting up WordPress and WooCommerce API access using Application Passwords and Consumer Keys.

## When to Use This Skill

Activate this skill when user needs help with:
- Initial plugin configuration for a project
- Generating WordPress Application Passwords
- Creating WooCommerce API keys (Consumer Key/Secret)
- Troubleshooting authentication issues
- Understanding HTTPS requirements
- Reconfiguring credentials for a site

## Quick Setup Overview

1. **Run initialization command**: `/wc-wp:init`
2. **Generate WordPress Application Password** (in WP admin)
3. **Generate WooCommerce API Keys** (if using WooCommerce)
4. **Test connection** (automatic validation)
5. **Start using WordPress/WooCommerce tools**

## WordPress Application Password Setup

### What is an Application Password?

Application Passwords are a built-in WordPress feature (since WP 5.6) that allows external applications to authenticate without using your main account password. They are:
- More secure than your main password
- Can be revoked individually
- Don't require additional plugins
- Work only over HTTPS

### Step-by-Step Generation

1. **Log into WordPress Admin Dashboard**
   - Navigate to your WordPress site
   - Access `/wp-admin/`
   - Log in with your admin credentials

2. **Navigate to Your Profile**
   - Click on "Users" in the admin sidebar
   - Click "Profile" or "Your Profile"
   - Alternatively: Users → All Users → (click your username)

3. **Find Application Passwords Section**
   - Scroll down to the "Application Passwords" section
   - If you don't see this section:
     - Your site may not be using HTTPS (Application Passwords require HTTPS)
     - Check WordPress version (must be 5.6+)
     - Some security plugins may disable this feature

4. **Generate New Application Password**
   - In "New Application Password Name" field, enter: **Claude Code**
   - Click "Add New Application Password" button
   - A password will be generated (format: `xxxx xxxx xxxx xxxx xxxx xxxx`)

5. **Copy the Password**
   - **CRITICAL**: Copy the password immediately - it will not be shown again
   - The password contains spaces - copy the entire string as-is
   - Store it temporarily (you'll enter it during `/wc-wp:init`)

### Common Issues

**"Application Passwords section is missing"**:
- Ensure site uses HTTPS (not HTTP) - Application Passwords require SSL
- Verify WordPress version 5.6 or higher
- Check if security plugin is blocking the feature (Wordfence, iThemes Security, etc.)
- Some hosts disable Application Passwords - contact hosting support

**"Invalid username or password" error**:
- Verify username matches WordPress admin username exactly
- Ensure you copied the entire Application Password (including spaces)
- Try removing spaces from password - plugin handles this automatically
- Regenerate Application Password if corrupted

**"REST API is disabled" error**:
- Go to Settings → Permalinks
- Change from "Plain" to any other option (e.g., "Post name")
- Save changes
- REST API requires pretty permalinks

## WooCommerce API Keys Setup

### What are WooCommerce API Keys?

WooCommerce uses OAuth 1.0a authentication with Consumer Key and Consumer Secret for API access. These credentials:
- Are separate from WordPress authentication
- Have configurable permissions (Read, Write, Read/Write)
- Can be generated per user
- Are specific to WooCommerce endpoints

### Step-by-Step Generation

1. **Ensure WooCommerce is Installed**
   - WooCommerce must be active on your WordPress site
   - Check: Plugins → Installed Plugins → WooCommerce should be "Active"

2. **Navigate to WooCommerce Settings**
   - In WordPress admin, click "WooCommerce" in sidebar
   - Click "Settings"
   - Click "Advanced" tab at the top
   - Click "REST API" sub-tab

3. **Add New API Key**
   - Click "Add key" button
   - Fill in the form:
     - **Description**: Claude Code
     - **User**: Select your admin user
     - **Permissions**: Select "Read/Write"
   - Click "Generate API Key" button

4. **Copy Credentials**
   - After generation, you'll see:
     - **Consumer Key**: Starts with `ck_`
     - **Consumer Secret**: Starts with `cs_`
   - **CRITICAL**: Copy both immediately - Consumer Secret won't be shown again
   - Consumer Key remains visible, but regenerating will change both

5. **Store Credentials**
   - Keep these temporarily for `/wc-wp:init` command
   - Will be stored in `.claude/woocommerce-wordpress.local.md` (gitignored)

### Common Issues

**"WooCommerce settings not found"**:
- Verify WooCommerce plugin is installed and activated
- Some WooCommerce versions have different menu structures
- Try: WooCommerce → Settings → API → Keys/Apps

**"Unauthorized" or "Invalid signature" errors**:
- Verify Consumer Key starts with `ck_`
- Verify Consumer Secret starts with `cs_`
- Ensure HTTPS is enabled (WooCommerce API requires it)
- Check keys have "Read/Write" permissions (not just "Read")
- Regenerate keys if corrupted

**"WooCommerce API is disabled"**:
- Go to WooCommerce → Settings → Advanced → REST API
- Ensure REST API is enabled
- Check that no security plugin is blocking API access

## Running the Initialization Command

Once you have credentials ready:

```bash
/wc-wp:init
```

The command will:
1. Prompt for WordPress site URL (must be `https://`)
2. Ask for WordPress username and Application Password
3. Ask if WooCommerce is enabled
4. If yes, ask for Consumer Key and Consumer Secret
5. Ask for backup preferences (storage location, retention, format)
6. Create `.claude/woocommerce-wordpress.local.md` configuration file
7. **Immediately test credentials** with API calls
8. Report connection status

### Testing Connection

After init, the plugin automatically tests connectivity:

**WordPress Test**:
- Attempts to fetch current user information
- If successful: Shows your WordPress username and user ID
- If failed: Shows error with troubleshooting guidance

**WooCommerce Test** (if enabled):
- Attempts to fetch WooCommerce system status
- If successful: Shows WooCommerce version
- If failed: Shows error with troubleshooting guidance

### Troubleshooting Failed Connections

If WordPress connection fails:
1. Verify HTTPS is enabled on site
2. Check Application Password was copied correctly
3. Ensure WordPress username is exact (case-sensitive)
4. Try regenerating Application Password
5. Check WordPress REST API is accessible: `https://yoursite.com/wp-json/`

If WooCommerce connection fails:
1. Verify WooCommerce plugin is active
2. Check Consumer Key and Consumer Secret are correct
3. Ensure API keys have "Read/Write" permissions
4. Verify keys are for the correct WordPress user
5. Check WooCommerce REST API: `https://yoursite.com/wp-json/wc/v3/`

## HTTPS Requirement

Both WordPress and WooCommerce APIs require HTTPS for security:

**Why HTTPS is Required**:
- Application Passwords only work over HTTPS (WordPress security requirement)
- API credentials are transmitted - must be encrypted
- WordPress REST API best practice
- WooCommerce requirement for production use

**How to Enable HTTPS**:
- Contact your hosting provider (most offer free SSL certificates)
- Use Let's Encrypt (free SSL certificate authority)
- Many hosts enable HTTPS by default
- Check hosting control panel for SSL/HTTPS settings

**Testing HTTPS**:
- Visit your site - URL should show `https://` with padlock icon
- Check: `https://yoursite.com/wp-admin/` should load without warnings
- Mixed content warnings indicate some resources still use HTTP

## Configuration File Structure

After running `/wc-wp:init`, your configuration is stored in:

```
.claude/woocommerce-wordpress.local.md
```

**File format**:
```yaml
---
site_url: https://yoursite.com
wordpress:
  username: admin
  app_password: xxxx xxxx xxxx xxxx xxxx xxxx
woocommerce:
  enabled: true
  consumer_key: ck_xxxxxxxxxxxxxxxxxxxxx
  consumer_secret: cs_xxxxxxxxxxxxxxxxxxxxx
backup:
  auto_backup: true
  storage: ./backups
  format: both
  retention_days: 30
---

# WordPress & WooCommerce Configuration

Configuration created: 2025-12-25
```

### Security Notes

- This file is automatically added to `.gitignore` - never committed to git
- Permissions: Only readable by you (your user account)
- Credentials stored in plain text (standard for .local.md files)
- Alternative: Use environment variables (see references/environment-variables.md)

### Updating Configuration

To update credentials or settings:
1. Edit `.claude/woocommerce-wordpress.local.md` directly, OR
2. Run `/wc-wp:init` again (will ask about overwriting)
3. Changes take effect immediately (no restart needed)

## Using Environment Variables (Optional)

For added security, use environment variables instead of plain text:

```yaml
wordpress:
  username: admin
  app_password: ${WP_APP_PASSWORD}
woocommerce:
  consumer_key: ${WC_CONSUMER_KEY}
  consumer_secret: ${WC_CONSUMER_SECRET}
```

Then set environment variables in your shell:
```bash
export WP_APP_PASSWORD="xxxx xxxx xxxx xxxx xxxx xxxx"
export WC_CONSUMER_KEY="ck_xxxxxxxxxxxxx"
export WC_CONSUMER_SECRET="cs_xxxxxxxxxxxxx"
```

See `references/environment-variables.md` for detailed setup.

## WordPress-Only Sites (No WooCommerce)

If your site doesn't use WooCommerce:
1. During `/wc-wp:init`, answer "No" to "Is WooCommerce enabled?"
2. Configuration will only include WordPress credentials
3. WooCommerce tools won't be available (expected)
4. All WordPress tools work normally

## Multi-Site Configuration

For managing multiple WordPress/WooCommerce sites:
- Each project has its own `.claude/woocommerce-wordpress.local.md`
- Configuration is per-project, not global
- Switch between projects by changing directories
- Each site can have different credentials and settings

## Next Steps After Setup

Once configured:
1. **Generate project README**: Run `/wc-wp:readme` for project-specific documentation
2. **Test basic operations**: Try "Show me all posts" or "List products"
3. **Create initial backup**: Run `/wc-wp:backup` to create baseline backup
4. **Explore tools**: Ask "What WordPress operations can you do?"

## Utility Scripts

This skill includes helpful utility scripts in `scripts/`:

- `test-connection.sh` - Test WordPress/WooCommerce API connectivity
- `generate-app-password.md` - Screenshot guide for Application Password generation
- `generate-wc-keys.md` - Screenshot guide for WooCommerce API keys

Run scripts directly or reference them for detailed step-by-step guidance.

## Additional Resources

- `references/wordpress-rest-api.md` - WordPress REST API documentation and endpoints
- `references/woocommerce-api.md` - WooCommerce API documentation and endpoints
- `references/environment-variables.md` - Using environment variables for credentials
- `references/troubleshooting.md` - Common issues and solutions
- `examples/config-examples.md` - Sample configuration files for different scenarios

---

**Remember**: HTTPS is mandatory. Both WordPress and WooCommerce require secure connections for API access.