Getting Started

This guide will help you install localpress and connect your first WordPress site.

Installation#

Option 1: Homebrew (Recommended)#

brew install gfargo/localpress/localpress

This installs everything you need in one command — including Bun (the runtime) and sharp (image processing) as dependencies. No further setup required.

Option 2: Archive Download#

Download the latest tarball from GitHub Releases:

# macOS (Apple Silicon)
curl -L https://github.com/gfargo/localpress/releases/latest/download/localpress-darwin-arm64.tar.gz | tar xz
ln -s "$(pwd)/localpress-darwin-arm64/bin/localpress" /usr/local/bin/localpress

# macOS (Intel)
curl -L https://github.com/gfargo/localpress/releases/latest/download/localpress-darwin-x64.tar.gz | tar xz
ln -s "$(pwd)/localpress-darwin-x64/bin/localpress" /usr/local/bin/localpress

# Linux (x64)
curl -L https://github.com/gfargo/localpress/releases/latest/download/localpress-linux-x64.tar.gz | tar xz
ln -s "$(pwd)/localpress-linux-x64/bin/localpress" /usr/local/bin/localpress

# Linux (ARM64)
curl -L https://github.com/gfargo/localpress/releases/latest/download/localpress-linux-arm64.tar.gz | tar xz
ln -s "$(pwd)/localpress-linux-arm64/bin/localpress" /usr/local/bin/localpress

The archive contains everything needed (bundle, dependencies, wrapper script). You only need Bun installed:

curl -fsSL https://bun.sh/install | bash

Option 3: From Source#

Requires Bun >= 1.1.0:

git clone https://github.com/gfargo/localpress.git
cd localpress
bun install
bun run dev -- --help    # run from source
# or build a distributable tarball:
bun run build            # → ./dist/localpress-<platform>.tar.gz

Verify Installation#

localpress --version
localpress doctor

doctor checks that everything is set up correctly, including image processing support.

Enable Shell Completions (Optional)#

Tab completion makes localpress much faster to use:

# Bash
localpress completions bash >> ~/.bashrc

# Zsh
localpress completions zsh >> ~/.zshrc

# Fish
localpress completions fish > ~/.config/fish/completions/localpress.fish

Restart your shell or source the config file to activate.

Keeping Up to Date#

# Homebrew users
brew upgrade localpress

# Archive users — self-update in place
localpress update

# Just check if an update is available
localpress update --check

Connect Your First WordPress Site#

Step 1: Create an Application Password#

1. Go to your WordPress admin: https://your-site.com/wp-admin
2. Navigate to Users → Profile
3. Scroll to Application Passwords
4. Enter a name (e.g., "localpress") and click Add New Application Password
5. Copy the generated password (it will look like: xxxx xxxx xxxx xxxx xxxx xxxx)

Step 2: Run the Setup Wizard#

localpress init

The interactive wizard will guide you through:

• Entering your WordPress site URL
• Choosing a name for this site configuration
• Entering your WordPress username
• Entering the Application Password

Step 3: Verify Connection#

localpress doctor

This command checks:

• REST API connectivity
• Available capabilities
• Installed WordPress plugins
• Authentication

Your First Commands#

List Media#

localpress list

Shows all media items in your WordPress library.

Run an Audit#

localpress audit

Checks for:

• Unoptimized images
• Large files (>1MB)
• Missing alt text
• Display size mismatches
• Duplicate images
• Broken references

Optimize Images#

# Dry run (see what would be optimized)
localpress optimize --unoptimized

# Actually optimize
localpress optimize --unoptimized --apply

Remove Backgrounds#

localpress remove-bg 123
# Where 123 is the attachment ID

# Preview model/threshold/background choices before applying
localpress remove-bg 123 --preview

# Fast lightweight model
localpress remove-bg 123 --model u2netp

The model downloads on first use, is checksum-verified, and is reused from the local cache. Batch runs share one loaded model session; built-in background removal uses at most two concurrent workers to keep memory use predictable. Output is a transparent PNG by default, with EXIF orientation and any existing source transparency preserved.

Next Steps#

• Learn about all available commands: localpress --help
• Export your library for backup: localpress export --all --to ./backup.zip
• Bulk import images: localpress import ./photos/ --optimize --to webp
• Set up named optimization profiles: See Configuration
• Integrate with AI agents: See AI Agent Integration
• Automate with bulk operations: See Commands Reference