wordpress-setup

jezweb ｜ 部署與發布 ｜ 原文 ｜ MIT

用 WP-CLI over SSH 或 REST API 連上 WordPress 並驗證存取

---
name: wordpress-setup
description: "透過 SSH 上的 WP-CLI 或 REST API 連接到 WordPress 網站。檢查 CLI、測試 SSH、設定驗證、驗證存取、儲存設定。只要使用者想連接 WordPress 網站、設定 WP-CLI 存取、建立 Application Password，或排查 WordPress 連線 / 驗證問題，就用這個 skill。"
compatibility: claude-code-only
---

# WordPress Setup

連接到 WordPress 網站，並透過 WP-CLI 或 REST API 驗證存取可用。產出一份驗證過的連線設定，可以直接拿來做內容管理和 Elementor 編輯。

## 工作流程

### 步驟 1：檢查 WP-CLI

```bash
wp --version
```

如果沒有安裝，引導使用者：

```bash
# macOS/Linux
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
```

同時確認有 SSH 擴充功能（遠端網站需要）：

```bash
wp package install wp-cli/ssh-command
```

### 步驟 2：連接到網站

**選項 A：透過 SSH 使用 WP-CLI（建議）**

```bash
wp --ssh=user@hostname/path/to/wordpress option get siteurl
```

常見的寫法：
- Rocket.net：`wp --ssh=user@hostname/www/sitename/public option get siteurl`
- cPanel：`wp --ssh=user@hostname/public_html option get siteurl`
- 自訂：問使用者 SSH 使用者、主機和 WordPress 路徑

先用簡單的指令測試：

```bash
wp --ssh=user@host/path core version
```

**選項 B：用 Application Password 的 REST API**

如果 SSH 不可用：

1. 前往 `https://example.com/wp-admin/profile.php`（或使用瀏覽器自動化）
2. 捲到 "Application Passwords" 區塊
3. 輸入名稱（例如 "Claude Code"），點 "Add New Application Password"
4. 複製產生的密碼（空格是密碼的一部分，但在驗證時可有可無）

測試連線：

```bash
curl -s https://example.com/wp-json/wp/v2/posts?per_page=1 \
  -u "username:xxxx xxxx xxxx xxxx xxxx xxxx" | jq '.[0].title'
```

### 步驟 3：儲存憑證

**WP-CLI SSH**：在專案根目錄建立 `wp-cli.yml`：

```yaml
ssh:
  sitename:
    cmd: ssh -o StrictHostKeyChecking=no %pseudotty% user@hostname %cmd%
    url: /path/to/wordpress
```

之後這樣用：`wp @sitename option get siteurl`

**REST API**：存在 `.dev.vars`：

```
WP_SITE_URL=https://example.com
WP_USERNAME=admin
WP_APP_PASSWORD=xxxx xxxx xxxx xxxx xxxx xxxx
```

確認 `.dev.vars` 在 `.gitignore` 裡。跨專案使用的話，存在你慣用的 secrets 管理工具（環境變數、1Password CLI 等）。

### 步驟 4：驗證完整存取

執行完整的檢查：

```bash
# Site info
wp @sitename option get siteurl
wp @sitename option get blogname

# Content access
wp @sitename post list --post_type=page --posts_per_page=5 --fields=ID,post_title,post_status

# Plugin status (check for Elementor)
wp @sitename plugin status elementor

# Theme info
wp @sitename theme status
```

### 步驟 5：儲存網站設定

建立 `wordpress.config.json`，讓其他 skill 參考：

```json
{
  "site": "example.com",
  "siteUrl": "https://example.com",
  "accessMethod": "ssh",
  "sshAlias": "sitename",
  "wpPath": "/path/to/wordpress",
  "hasElementor": true,
  "elementorVersion": "3.x.x"
}
```

---

## 關鍵模式

### SSH 連線問題

| 症狀 | 解法 |
|---------|-----|
| `Permission denied (publickey)` | 檢查 SSH key：`ssh -v user@host` |
| 透過 SSH 出現 `wp: command not found` | WP-CLI 不在遠端的 PATH 裡，用完整路徑：`/usr/local/bin/wp` |
| `Error: This does not appear to be a WordPress installation` | 路徑錯誤，檢查 `wp-path` 參數 |
| 大型操作逾時 | 加上 `--ssh=user@host/path --allow-root`，或增加 SSH 逾時時間 |

### WP-CLI Alias

為常用的網站在 `~/.wp-cli/config.yml` 定義 alias：

```yaml
@client1:
  ssh: user@client1.example.com/www/public
@client2:
  ssh: user@client2.rocketcdn.me/www/client2/public
```

之後：`wp @client1 post list`

### REST API 陷阱

- Application password 需要 HTTPS（HTTP 不能用）
- 有些安全外掛會擋 REST API，檢查有沒有 401/403 回應
- 快取外掛可能會回傳過期的 REST 回應，用 `?_=${timestamp}` 破壞快取
- 自訂 post type 需要 `show_in_rest: true` 才會出現在 API 裡

---

## 參考檔案

- `references/wp-cli-essentials.md`：SSH alias 模式、常用 flag 和疑難排解

---
name: wordpress-setup
description: "Connect to a WordPress site via WP-CLI over SSH or the REST API. Check CLI, test SSH, set up auth, verify access, save config. Use whenever the user wants to connect to a WordPress site, set up WP-CLI access, create an Application Password, or troubleshoot WordPress connection / auth issues."
compatibility: claude-code-only
---

# WordPress Setup

Connect to a WordPress site and verify working access via WP-CLI or REST API. Produces a verified connection config ready for content management and Elementor editing.

## Workflow

### Step 1: Check WP-CLI

```bash
wp --version
```

If not installed, guide the user:

```bash
# macOS/Linux
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
```

Also ensure the SSH extension is available (needed for remote sites):

```bash
wp package install wp-cli/ssh-command
```

### Step 2: Connect to the Site

**Option A: WP-CLI over SSH (preferred)**

```bash
wp --ssh=user@hostname/path/to/wordpress option get siteurl
```

Common patterns:
- Rocket.net: `wp --ssh=user@hostname/www/sitename/public option get siteurl`
- cPanel: `wp --ssh=user@hostname/public_html option get siteurl`
- Custom: Ask user for SSH user, host, and WordPress path

Test with a simple command first:

```bash
wp --ssh=user@host/path core version
```

**Option B: REST API with Application Password**

If SSH isn't available:

1. Navigate to `https://example.com/wp-admin/profile.php` (or use browser automation)
2. Scroll to "Application Passwords" section
3. Enter a name (e.g. "Claude Code") and click "Add New Application Password"
4. Copy the generated password (spaces are part of it but optional in auth)

Test the connection:

```bash
curl -s https://example.com/wp-json/wp/v2/posts?per_page=1 \
  -u "username:xxxx xxxx xxxx xxxx xxxx xxxx" | jq '.[0].title'
```

### Step 3: Store Credentials

**For WP-CLI SSH** — create a `wp-cli.yml` in the project root:

```yaml
ssh:
  sitename:
    cmd: ssh -o StrictHostKeyChecking=no %pseudotty% user@hostname %cmd%
    url: /path/to/wordpress
```

Then use: `wp @sitename option get siteurl`

**For REST API** — store in `.dev.vars`:

```
WP_SITE_URL=https://example.com
WP_USERNAME=admin
WP_APP_PASSWORD=xxxx xxxx xxxx xxxx xxxx xxxx
```

Ensure `.dev.vars` is in `.gitignore`. For cross-project use, store in your preferred secrets manager (environment variable, 1Password CLI, etc.).

### Step 4: Verify Full Access

Run a comprehensive check:

```bash
# Site info
wp @sitename option get siteurl
wp @sitename option get blogname

# Content access
wp @sitename post list --post_type=page --posts_per_page=5 --fields=ID,post_title,post_status

# Plugin status (check for Elementor)
wp @sitename plugin status elementor

# Theme info
wp @sitename theme status
```

### Step 5: Save Site Config

Create `wordpress.config.json` for other skills to reference:

```json
{
  "site": "example.com",
  "siteUrl": "https://example.com",
  "accessMethod": "ssh",
  "sshAlias": "sitename",
  "wpPath": "/path/to/wordpress",
  "hasElementor": true,
  "elementorVersion": "3.x.x"
}
```

---

## Critical Patterns

### SSH Connection Issues

| Symptom | Fix |
|---------|-----|
| `Permission denied (publickey)` | Check SSH key: `ssh -v user@host` |
| `wp: command not found` via SSH | WP-CLI not in remote PATH — use full path: `/usr/local/bin/wp` |
| `Error: This does not appear to be a WordPress installation` | Wrong path — check `wp-path` argument |
| Timeout on large operations | Add `--ssh=user@host/path --allow-root` or increase SSH timeout |

### WP-CLI Aliases

Define aliases in `~/.wp-cli/config.yml` for frequently-accessed sites:

```yaml
@client1:
  ssh: user@client1.example.com/www/public
@client2:
  ssh: user@client2.rocketcdn.me/www/client2/public
```

Then: `wp @client1 post list`

### REST API Gotchas

- Application passwords require HTTPS (won't work on HTTP)
- Some security plugins block REST API — check for 401/403 responses
- Caching plugins may serve stale REST responses — use `?_=${timestamp}` cache buster
- Custom post types need `show_in_rest: true` to appear in API

---

## Reference Files

- `references/wp-cli-essentials.md` — SSH alias patterns, common flags, and troubleshooting