WP-CLI SSH Setup

localPress uses the WordPress REST API by default — it works against any install with Application Passwords and requires no server access. For operations that need direct filesystem control, localPress delegates to WP-CLI over SSH.

What WP-CLI unlocks

Run localpress doctor at any time to see which capabilities are active.

Prerequisites

1. SSH access to your WordPress server (key-based, passwordless recommended)
2. WP-CLI installed on the server — run wp --info over SSH to confirm
3. Your SSH public key in ~/.ssh/authorized_keys on the server

Quick setup via init wizard

The easiest way to configure SSH is during site setup:

localpress init

After authenticating via REST API, the wizard will ask if you want to configure SSH. It will prompt for each field and test the connection automatically.

Manual configuration

Option 1: Edit config.json directly

Find your config file:

localpress config get
# Prints the config file path — typically ~/.config/localpress/config.json

Add an ssh object to your site entry:

{
  "sites": {
    "my-site": {
      "url": "https://example.com",
      "username": "wp-admin",
      "appPassword": "xxxx xxxx xxxx xxxx xxxx xxxx",
      "ssh": {
        "host": "example.com",
        "user": "deploy",
        "port": 22,
        "wpPath": "/var/www/html",
        "identityFile": "~/.ssh/id_ed25519"
      }
    }
  }
}

Option 2: Use localpress config set

localpress config set sites.my-site.ssh.host example.com
localpress config set sites.my-site.ssh.user deploy
localpress config set sites.my-site.ssh.port 22
localpress config set sites.my-site.ssh.wpPath /var/www/html
localpress config set sites.my-site.ssh.identityFile ~/.ssh/id_ed25519

SSH config fields

Field details

host — The hostname or IP address of your server. This is just the host, not user@host. Examples:

• example.com
• 203.0.113.42
• ssh.mysite.kinsta.cloud

user — The SSH username you log in as. This is the system user on the server, not your WordPress username. Examples:

• deploy
• ubuntu
• root
• mysite (managed hosts)

wpPath — The absolute filesystem path to your WordPress root directory on the remote server. This is where wp-config.php lives. It is NOT the path to the wp CLI binary. Examples:

• /var/www/html
• /var/www/wordpress
• /home/user/public_html
• /www/mysite_123/public

To find it, SSH in and run: find / -name wp-config.php 2>/dev/null

identityFile — Path to your SSH private key. If omitted, localpress uses your SSH agent or falls back to ~/.ssh/id_rsa. Examples:

• ~/.ssh/id_ed25519
• ~/.ssh/id_rsa
• ~/.ssh/my-server-key

Verify the setup

localpress doctor

You should see ✓ WP-CLI (SSH) and the previously unavailable capabilities now marked ✓.

Common hosting setups

VPS / DigitalOcean / Linode

Typically straightforward — your SSH user needs read/write access to the WordPress directory. WP-CLI must be installed system-wide (/usr/local/bin/wp) or in the user's PATH.

"ssh": {
  "host": "203.0.113.42",
  "user": "ubuntu",
  "port": 22,
  "wpPath": "/var/www/wordpress"
}

Kinsta / WP Engine / Managed hosts

Managed WordPress hosts expose SSH via a custom port and hostname available in your hosting dashboard. WP-CLI is typically pre-installed.

"ssh": {
  "host": "ssh.mysite.kinsta.cloud",
  "user": "mysite",
  "port": 12345,
  "wpPath": "/www/mysite_123/public"
}

Shared hosting (cPanel)

Many shared hosts (SiteGround, Bluehost) offer SSH access. WP-CLI may need to be installed manually — see wp-cli.org for a single-file install:

curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar
chmod +x wp-cli.phar
mv wp-cli.phar ~/bin/wp

"ssh": {
  "host": "server123.siteground.com",
  "user": "u1234-abcde",
  "port": 18765,
  "wpPath": "/home/u1234-abcde/public_html"
}

GridPane / SpinupWP / RunCloud

Server management panels typically use root or a dedicated system user. Check your panel's SSH documentation for the correct user and port.

"ssh": {
  "host": "my-server.gridpane.cloud",
  "user": "root",
  "wpPath": "/var/www/example.com/htdocs"
}

Troubleshooting

✗ WP-CLI (SSH) after configuring

Run localpress doctor — the error message will show the exact SSH failure. Common causes:

Permission denied on replace-in-place

The SSH user must own (or have write access to) the wp-content/uploads/ directory. Fix:

# On the server:
chown -R deploy:www-data wp-content/uploads/
chmod -R 775 wp-content/uploads/

WP-CLI found but wpPath wrong

WP-CLI looks for wp-config.php in wpPath. If your WordPress is in a subdirectory (e.g. /var/www/html/wordpress), make sure wpPath points all the way in.

SSH works manually but not from localpress

localpress uses BatchMode=yes which disables password prompts. Make sure:

1. Your key is loaded in ssh-agent (ssh-add -l) or identityFile is set
2. The key doesn't require a passphrase (or your agent has it unlocked)
3. Your ~/.ssh/config isn't overriding settings in a way that conflicts

Testing SSH manually

You can replicate what localpress does:

# Basic connection test:
ssh -o BatchMode=yes -o StrictHostKeyChecking=accept-new user@host -p 22 "wp --info --path=/var/www/html"

# With identity file:
ssh -i ~/.ssh/id_ed25519 -o BatchMode=yes user@host "cd /var/www/html && wp --info --allow-root"