Skip to content

Document ssh+path configuration limitation in wp-cli.yml #622

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
Copilot wants to merge 2 commits into
base: main
Choose a base branch
from
+23 −0
Draft

Document ssh+path configuration limitation in wp-cli.yml #622

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7b8ce19
Initial plan
Copilot Feb 2, 2026
6db8de1
Document ssh+path configuration limitation and workarounds
Copilot Feb 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 23 additions & 0 deletions references/config.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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):
```
Copy link

Copilot AI Feb 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The first code block is missing the yaml language marker. The second code block at line 348 has yaml marker, but this one doesn't. For consistency, both should have the same format.

Suggested change
```
```yaml

Copilot uses AI. Check for mistakes.
# 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:
Copy link

Copilot AI Feb 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The wording "may not be applied correctly" is vague. Based on the original issue description, the path option is actually ignored (not applied at all), not just incorrectly applied. Consider changing this to "the path option is not applied" or "the path option will be ignored" for more accurate documentation.

Suggested change
**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:
**Important:** When using `ssh` and `path` as separate top-level options in `wp-cli.yml` (not within an alias), the `path` option will be ignored. In such cases, use one of the following workarounds:

Copilot uses AI. Check for mistakes.

* 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`
Expand Down