Configuration

localpress stores configuration in ~/.config/localpress/ (macOS/Linux) or %APPDATA%\localpress\ (Windows).

Config File Location

Platform	Path
macOS/Linux	~/.config/localpress/config.json
Windows	%APPDATA%\localpress\config.json
Custom	Set $XDG_CONFIG_HOME environment variable

Site Configuration

Each WordPress site you connect creates:

1. An entry in config.json
2. A SQLite database at ~/.config/localpress/sites/<name>.db

Example config.json

{
  "activeSite": "production",
  "sites": {
    "production": {
      "url": "https://example.com",
      "username": "admin",
      "appPassword": "xxxx xxxx xxxx xxxx xxxx xxxx",
      "ssh": {
        "host": "example.com",
        "user": "deploy",
        "port": 22,
        "wpPath": "/var/www/html",
        "identityFile": "~/.ssh/id_ed25519"
      }
    },
    "staging": {
      "url": "https://staging.example.com",
      "username": "admin",
      "appPassword": "yyyy yyyy yyyy yyyy yyyy yyyy"
    }
  },
  "defaults": {
    "quality": 80,
    "format": "webp",
    "stripMetadata": true
  },
  "profiles": {
    "hero": {
      "quality": 75,
      "format": "webp",
      "maxWidth": 1920,
      "description": "Hero images"
    },
    "thumbnail": {
      "quality": 85,
      "maxWidth": 400,
      "stripMetadata": true
    }
  }
}

Managing Sites

List Sites

localpress sites

Switch Active Site

localpress sites use production

Add a Site

localpress sites add production --url https://example.com

Remove a Site

localpress sites remove staging

Optimization Profiles

Profiles are reusable optimization presets.

Create a Profile

localpress config set-profile hero --quality 75 --format webp --max-width 1920

Use a Profile

localpress optimize 123 --profile hero

List Profiles

localpress config list-profiles

Available Profile Options

• --quality: JPEG/WebP/AVIF quality (1-100)
• --format: Output format (jpeg, webp, avif, png)
• --max-width: Maximum width in pixels
• --max-height: Maximum height in pixels
• --strip-metadata: Remove EXIF data (true/false)
• --auto-orient: Apply EXIF rotation (true/false)
• --encoder: Backend encoder (sharp, jsquash)

Global Defaults

Set defaults that apply to all commands:

# Set default quality
localpress config set defaults.quality 80

# Set default format
localpress config set defaults.format webp

# Set default concurrency
localpress config set defaults.concurrency 4

# Set the default Ollama vision model for `caption`
# (works around `moondream` being the built-in default when you've pulled
# a different vision model)
localpress config set defaults.captionModel llava-llama3:latest

Defaults are used when options aren't explicitly provided. For caption, the resolution order is --model <flag> > config.defaults.captionModel > the built-in default (moondream).

SSH Configuration (WP-CLI)

For replace-in-place operations and other server-side capabilities, localpress can use WP-CLI over SSH.

See the full WP-CLI SSH Setup guide for detailed instructions.

Configure SSH via init wizard

The easiest way — the wizard prompts for all fields and tests the connection:

localpress init

Configure SSH manually

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

SSH config fields

Field	Required	Default	Description
host	✓	—	SSH hostname or IP (not user@host)
user	✓	—	SSH username on the server
port		22	SSH port
wpPath	✓	—	Absolute path to WordPress root (where wp-config.php lives)
identityFile		ssh-agent	Path to SSH private key

Test SSH Connection

localpress doctor

Security Considerations

Application Passwords

• Stored encrypted in config file
• Can be revoked from WordPress admin at any time
• Scope-limited to media operations only

SSH Keys

• Private keys never leave your machine
• Use passphrase-protected keys
• Revoke access from hosting control panel if compromised

Config File Permissions

Config files are created with 0600 permissions (owner read/write only).

Environment Variables

Variable	Purpose
LOCALPRESS_CONFIG_DIR	Override config directory
LOCALPRESS_SITE	Override active site
LOCALPRESS_CONCURRENCY	Override default concurrency
LOCALPRESS_DRY_RUN	Force dry-run mode (1=true)

Migration

Export & Import

The fastest way to migrate media between sites:

# Export from production
localpress export --all --to ./migration.zip --site production

# Import into staging with optimization
localpress import ./migration.zip --optimize --to webp --preserve-ids --site staging

The --preserve-ids flag reads the manifest from a previous export to restore alt text, titles, captions, and descriptions on the new site.

Backup Config

cp ~/.config/localpress/config.json ~/backup/localpress-config.json
cp -r ~/.config/localpress/sites ~/backup/

Restore Config

cp ~/backup/localpress-config.json ~/.config/localpress/config.json
cp -r ~/backup/sites ~/.config/localpress/

Share Config Between Machines

1. Copy config.json (redact passwords first)
2. Copy SQLite databases (sites/*.db)
3. Ensure SSH keys are available on both machines