From 7b8ce19ace3132ab1dbc9f2cf169a81fb7959573 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 2 Feb 2026 18:27:57 +0000
Subject: [PATCH 1/3] Initial plan


From 6db8de119d4a5a216252469db76162fffe907c8f Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 2 Feb 2026 18:30:17 +0000
Subject: [PATCH 2/3] Document ssh+path configuration limitation and
 workarounds

Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com>
---
 references/config.md | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/references/config.md b/references/config.md
index a09d1f39..84ff18c0 100644
--- a/references/config.md
+++ b/references/config.md
@@ -334,6 +334,29 @@ Supported types are:
 
 All connection types support an optional `path` suffix to specify a directory to `cd` to before running WP-CLI; `path` is a full system path starting with either `/` or `~`. (If `WP_CLI_SSH_PRE_CMD` is specified, `cd` is run after this pre-command.)
 
+### Using path with SSH
+
+When using SSH connections, you can specify the remote WordPress path in two ways:
+
+1. **As a suffix in the SSH connection string** (recommended):
+   ```
+   # Using the path suffix directly in the ssh parameter
+   ssh: user@host~/path/to/wordpress
+   ```
+
+2. **As a separate option in an alias**:
+   ```yaml
+   @staging:
+     ssh: user@host
+     path: /path/to/wordpress
+   ```
+
+**Important:** When using `ssh` and `path` as separate top-level options in `wp-cli.yml` (not within an alias), the `path` option may not be applied correctly. In such cases, use one of the following workarounds:
+
+* Include the path as a suffix in the SSH connection string (e.g., `ssh: user@host~/path/to/wordpress`)
+* Define an alias with both `ssh` and `path` options, then use the alias (e.g., `wp @staging command`)
+* Specify the path explicitly on the command line (e.g., `wp --path=/path/to/wordpress command`)
+
 The SSH connection type also supports two advanced connection configuration options, which must be specified via an alias in the YAML configuration:
 
 * `proxyjump` - Specifies a jumpbox connection string, which is passed to `ssh -J`

From b68e973d73a8dcc8b9d6f0057be5869a71259997 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 3 Feb 2026 14:50:32 +0000
Subject: [PATCH 3/3] Address PR review feedback: simplify documentation and
 fix formatting

Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com>
---
 references/config.md | 36 ++++++++++++++++--------------------
 1 file changed, 16 insertions(+), 20 deletions(-)

diff --git a/references/config.md b/references/config.md
index 84ff18c0..e709f51b 100644
--- a/references/config.md
+++ b/references/config.md
@@ -336,26 +336,22 @@ All connection types support an optional `path` suffix to specify a directory to
 
 ### Using path with SSH
 
-When using SSH connections, you can specify the remote WordPress path in two ways:
-
-1. **As a suffix in the SSH connection string** (recommended):
-   ```
-   # Using the path suffix directly in the ssh parameter
-   ssh: user@host~/path/to/wordpress
-   ```
-
-2. **As a separate option in an alias**:
-   ```yaml
-   @staging:
-     ssh: user@host
-     path: /path/to/wordpress
-   ```
-
-**Important:** When using `ssh` and `path` as separate top-level options in `wp-cli.yml` (not within an alias), the `path` option may not be applied correctly. In such cases, use one of the following workarounds:
-
-* Include the path as a suffix in the SSH connection string (e.g., `ssh: user@host~/path/to/wordpress`)
-* Define an alias with both `ssh` and `path` options, then use the alias (e.g., `wp @staging command`)
-* Specify the path explicitly on the command line (e.g., `wp --path=/path/to/wordpress command`)
+When using SSH connections, you must specify the remote WordPress path as a suffix in the SSH connection string:
+
+```yaml
+# Using the path suffix directly in the ssh parameter
+ssh: user@host~/path/to/wordpress
+```
+
+**Important:** When using `ssh` and `path` as separate top-level options in `wp-cli.yml`, the `path` option will be ignored. Always include the path as a suffix in the SSH connection string (e.g., `ssh: user@host~/path/to/wordpress`).
+
+Note: Within an alias definition, you can specify `ssh` and `path` as separate options:
+
+```yaml
+@staging:
+  ssh: user@host
+  path: /path/to/wordpress
+```
 
 The SSH connection type also supports two advanced connection configuration options, which must be specified via an alias in the YAML configuration: