Commands Reference

localpress has 36 commands organized into 10 categories. All commands support --json for machine-readable output and --help for detailed usage.

Setup Commands

init

Connect a WordPress site (interactive Ink wizard).

# Interactive wizard
localpress init

# Non-interactive
localpress init --url https://site.com --username admin --app-password "xxxx xxxx xxxx"

sites

List, add, switch, or remove configured sites.

# List all sites
localpress sites

# Switch active site
localpress sites use production

# Add a site
localpress sites add production --url https://site.com

# Remove a site
localpress sites remove staging

doctor

Show backend availability, plugin detection, and fix issues.

# Check connection and capabilities
localpress doctor

# Try to fix issues automatically
localpress doctor --fix

# Check plugin detection
localpress doctor --plugins

config

Read/write config values, manage named profiles.

# Set global defaults
localpress config set defaults.quality 80
localpress config set defaults.format webp

# Create a named optimization profile
localpress config set-profile hero --quality 75 --format webp --max-width 1920

# List all profiles
localpress config list-profiles

# Print full config
localpress config list

Discovery & Auditing Commands

list

Browse the media library with filters, sorting, and interactive TUI mode.

# List all media
localpress list

# List unoptimized images only
localpress list --unoptimized

# Free-text search across filename and title
localpress list --search hero
localpress list --search "logo" --type image/png

# List large images (>1MB)
localpress list --larger-than 1048576

# Sort by file size, largest first
localpress list --sort size

# Sort by name, alphabetically
localpress list --sort name --order asc

# Paginate through results
localpress list --page 2 --limit 25

# Interactive TUI browser (keyboard navigation + sidebar)
localpress list --interactive
localpress list -i

# List with JSON output
localpress list --json

Sort fields: date (default), name, size, id Sort order: desc (default), asc

The interactive TUI (-i) renders inline image thumbnails in supported terminals (iTerm2, Warp, WezTerm, Kitty). Your last page and cursor position are remembered across sessions. Keyboard shortcuts: ↑↓/jk navigate, ←→/nb page, / search, o optimize, O optimize+preview, r remove-bg, R remove-bg+preview, c convert, s resize, a caption, e edit, W open in WP admin, P open in browser, p inline preview, ↵ details, q quit.

stats

Library health dashboard and cumulative processing stats — all from local SQLite, no network calls.

# Show stats for the active site
localpress stats

# Show stats for every configured site
localpress stats --all-sites

# Machine-readable output
localpress stats --json

Output includes:

• Library overview: total attachments, total size, optimized/unoptimized counts with percentages
• Cumulative savings: bytes saved, average compression ratio
• Format breakdown: JPEG, PNG, WebP, AVIF counts with percentages
• Operation breakdown: per-operation stats with average duration
• Recent operations: grouped by date showing item counts and savings

show

Detailed metadata and processing history for a specific attachment.

localpress show 123
# Where 123 is the attachment ID

audit

Comprehensive library health check.

# Run all audit checks
localpress audit

# Run specific checks only
localpress audit --display-size --duplicates

# Export as JSON
localpress audit --json

Available audit checks:

• --unoptimized: Images never processed by localpress
• --large: Images over a size threshold (default 1MB)
• --missing-alt: Images without alt text
• --display-size: Images significantly larger than their largest WP thumbnail
• --duplicates: Perceptually identical images via dHash
• --broken-refs: Attachment URLs that 404
• --orphans: Files on disk with no DB record (requires WP-CLI)
• --quality: Blurry / low-contrast / poorly-composed images (Ollama vision; slow, ~10s/image, requires explicit opt-in)
• --ocr-text <term>: Images that visually contain the supplied text — useful for finding screenshots referencing a topic (Ollama vision; slow, requires explicit opt-in)

--quality and --ocr-text are not included in the default "run all checks" behavior because each calls the Ollama vision model per image (~10s each). They must be requested explicitly.

references

Find every post/page that uses an attachment.

localpress references 123
# Shows where attachment 123 is used

Processing Commands

optimize

Compress images with sharp or jSquash WASM codecs.

# Optimize specific attachments
localpress optimize 123 124 125

# Bulk optimize (dry-run by default)
localpress optimize --unoptimized
# Execute for real:
localpress optimize --unoptimized --apply

# Use jSquash WASM codecs for better PNG compression
localpress optimize 123 --encoder jsquash

# Use a named profile
localpress optimize 123 --profile hero

# Open browser preview to adjust settings before applying
localpress optimize 123 --preview

# Replace in place AND regenerate WP thumbnails (for same-format optimizations)
localpress optimize 123 --regenerate-thumbnails

Thumbnail regeneration: When the format changes (e.g., --to webp), thumbnails are always regenerated automatically — old-format thumbnails are deleted and fresh ones are created from the new source. For same-format optimizations (e.g., compressing a JPEG without converting), thumbnails are skipped by default for speed. Pass --regenerate-thumbnails to force regeneration, or run localpress regenerate separately for bulk regeneration.

convert

Format conversion (JPEG → WebP, PNG → AVIF).

# Convert to WebP
localpress convert 123 124 --to webp

# Convert to AVIF with custom quality
localpress convert 123 --to avif --quality 50

# Convert and replace original
localpress convert 123 --to webp --replace

resize

Resize preserving aspect ratio, regenerate thumbnails.

# Resize to max 1200px wide
localpress resize 123 124 --max-width 1200

# Resize to exact dimensions (crops if needed)
localpress resize 123 --width 800 --height 600

# Resize and regenerate WordPress thumbnails
localpress resize 123 --regenerate-thumbnails

caption

Generate alt-text for images using a local Ollama vision model. No cloud API. No credits.

Requires Ollama — see the Ollama Setup guide for installation and model recommendations.

# Caption specific attachments
localpress caption 123 124

# Bulk-caption all images with no alt text
localpress caption --missing-alt

# Caption all images in the library (dry-run by default)
localpress caption --all

# Execute the bulk caption run
localpress caption --missing-alt --apply

# Preview without writing to WordPress
localpress caption --missing-alt --dry-run

# Generate alt text in a specific language
localpress caption 123 --language Spanish
localpress caption --missing-alt --language French --apply

# Replace existing alt text
localpress caption 123 --overwrite

# Use a specific Ollama model
localpress caption 123 --model llava

# List locally available vision models
localpress caption --list-models

Recommended models: moondream (~1.7 GB, fast), llava (~4.7 GB, higher quality)

Language support: The --language flag instructs the model to generate alt text in the specified language. Works with any language the model supports (e.g. Spanish, French, German, Japanese, Chinese).

delete

Remove attachment(s) from WordPress. Captures undo snapshots first.

# Move to trash (default — recoverable from WP admin)
localpress delete 123 124 125

# Permanently delete (skip trash)
localpress delete 123 --force

# JSON output
localpress delete 123 --json

The default behavior moves attachments to the WordPress trash (recoverable from the admin). Pass --force to skip trash and permanently delete the attachment + file. Either way, the time-machine captures a binary snapshot of the file bytes first, so localpress undo --apply can re-upload the file (as a new attachment ID — references will need to be rewritten manually if you want them restored).

title

AI-generated short title (3-7 word noun phrase) written to the WP post_title field. Companion to caption/describe — same Ollama vision model, same pre-flight check, same time-machine snapshot.

# Title specific attachments
localpress title 123 124

# Bulk: only items whose title looks auto-generated (Screenshot-…, IMG_…, DSC_…)
localpress title --missing-title --apply

# Title every image (dry-run unless --apply)
localpress title --all --apply

# In a specific language
localpress title 123 --language Spanish

# Override with an explicit model
localpress title 123 --model llama3.2-vision:11b

The --missing-title filter detects machine-generated WP titles via simple heuristics: Screenshot-…, IMG_…, DSC_…, hex hashes, untitled, bare numbers.

rename

Rename attachment slugs (WordPress permalinks). Two modes:

# AI-generate the new name via Ollama vision, then slugify it
localpress rename 123 --smart

# Use an explicit name (slugified for you)
localpress rename 123 --to "Terminal command output"

# Multiple IDs
localpress rename 123 124 125 --smart

# Dry-run first
localpress rename 123 --smart --dry-run

The rename updates the WP slug (post_name), which controls the attachment's permalink (/?attachment=slug). It does not rename the underlying file on disk — that requires WP-CLI plus filesystem operations and is not yet supported. The visible filename in your media library is unaffected.

A metadata-only snapshot is captured before each rename so localpress undo can roll it back.

describe

AI-generated 2-3 sentence description for galleries and attachment-page SEO. Writes to the WP description field.

vision

Unified workflow — generate all AI metadata fields (alt, title, description, tags, classify) for one or more attachments in a single pass.

# Print-only (default): see what would be generated
localpress vision 123

# Write all fields to WP
localpress vision 123 --apply

# Subset of fields
localpress vision 123 --fields alt,title --apply

# Skip fields that already have values (default); pass --overwrite to replace
localpress vision 123 --apply --overwrite

# Multiple attachments
localpress vision 123 124 125 --apply

This is a per-attachment workflow (N Ollama calls per image, one per field), not a bulk-the-whole-library workflow — use the dedicated commands (caption, title, describe, tag, classify) with their --missing-* filters for library-wide passes.

When vision writes a classification, it's cached in the same place classify writes — so subsequent optimize calls on the same attachment will pick the smarter format default.

tag

AI-generated tags (3-6 short labels) written to the attachment caption as a [tags: tag1, tag2, …] block.

localpress tag 123 124

# Bulk: only items without an existing [tags: …] block
localpress tag --missing-tags --apply

# Replace existing tags
localpress tag 123 --overwrite

The tag block is appended to the existing caption rather than replacing it — so user-written captions stay intact. This approach doesn't require WP attachment taxonomies to be registered (which most plugins disable by default), making it work on any WordPress install.

classify

Detect image type — screenshot | photo | illustration | diagram — via the Ollama vision model. Cached locally so optimize can pick smarter format defaults.

# Classify specific attachments
localpress classify 123 124 125

# JSON
localpress classify 123 --json
# → {"classified":1,"failures":0,"results":[{"id":123,"classification":"screenshot",…}]}

When classification has been run on an attachment, optimize (called without an explicit --to and without a profile that sets a format) uses it:

• screenshot or diagram → defaults to PNG (preserves crisp text edges)
• photo or illustration → defaults to WebP (best photographic compression)

Explicit --to <format> or profile values always win.

localpress describe 123 124
localpress describe --missing-description --apply
localpress describe --all --apply
localpress describe 123 --language French

metadata

Directly set/edit attachment metadata. Use this when you already have the alt text (or title/caption/description) and don't need AI generation — caption/title/describe are for the AI paths.

# Set alt text on one attachment
localpress metadata 123 --alt-text "Screenshot of the dashboard"

# Set multiple fields at once
localpress metadata 123 --alt-text "..." --title "..." --caption "..." --description "..."

# Bulk: apply the same metadata to multiple IDs
localpress metadata 123 124 125 --alt-text "Product photo on white"

# JSON output
localpress metadata 123 --alt-text "..." --json

At least one of --alt-text, --title, --caption, or --description is required. Items whose incoming fields all match the current values are skipped. Each write captures a metadata-only snapshot so localpress undo can restore the previous values.

remove-bg

AI background removal using local ONNX Runtime.

# Remove background (downloads model on first use)
localpress remove-bg 123

# Remove background with white fill
localpress remove-bg 123 --bg "#ffffff"

# Use the best model (BiRefNet, state-of-the-art, ~224MB)
localpress remove-bg 123 --model birefnet-lite

# Use ISNet for better edge quality than U2-Net (~176MB)
localpress remove-bg 123 --model isnet-general-use

# Use lightweight model for faster processing (~4.7MB)
localpress remove-bg 123 --model u2netp

# Open browser preview to adjust model, threshold, and background
localpress remove-bg 123 --preview

# Use system Python rembg instead of built-in ONNX
localpress remove-bg 123 --rembg

Available models: birefnet-lite (best, MIT, ~224MB), isnet-general-use (great, Apache-2.0, ~176MB), u2net (default, Apache-2.0, ~176MB), silueta (balanced, ~44MB), u2netp (fast, ~4.7MB)

Server-side Commands

regenerate

Regenerate WordPress thumbnails via WP-CLI. Useful after bulk-optimizing without --regenerate-thumbnails, or after a theme change adds new image sizes.

# Regenerate specific attachments
localpress regenerate 123 124 125

# Bulk regeneration (dry-run by default)
localpress regenerate --all

# Execute bulk regeneration
localpress regenerate --all --apply

# Parallel execution
localpress regenerate --all --apply --concurrency 4

Requires WP-CLI (SSH) — check availability with localpress doctor.

Round-trip Editing Command

edit

Download → editor → watch → sync (the killer feature).

# Open in default editor, watch for saves, sync back
localpress edit 123

# Open in a specific app
localpress edit 123 --with "GIMP"
localpress edit 123 --with "Photoshop"

# Open without watching (manual upload later)
localpress edit 123 --no-watch

The edit command:

1. Downloads the attachment to a temporary directory
2. Opens it in your default image editor
3. Watches for file saves
4. Automatically uploads each save back to WordPress
5. Press Enter to stop watching

Automation Commands

watch

Watch a local directory for new or changed image files and automatically push them to WordPress.

# Watch a directory, push new/changed images
localpress watch ./assets/images

# Watch with optimization (compress before uploading)
localpress watch ./product-photos --optimize --quality 80

# Watch and convert to WebP on upload
localpress watch ./uploads --to webp

# Watch with resize constraints
localpress watch ./raw-photos --optimize --max-width 1920

# Auto-delete from WordPress when local files are removed
localpress watch ./media --delete

# Custom debounce for slow editors
localpress watch ./assets --debounce 1500

Behavior:

• New files → uploaded as new attachments
• Changed files → replaced in-place (WP-CLI) or uploaded as new (REST fallback)
• Deleted files → warning logged (default); deleted from WP with --delete

How it works:

1. Watches for .jpg, .jpeg, .png, .webp, .avif, .gif, .svg files
2. Debounces writes (handles editors that do atomic save via temp file → rename)
3. Computes SHA-256 hash — skips re-upload if content hasn't changed
4. Persists file→attachment mappings in SQLite (survives restarts)
5. Ctrl+C stops gracefully

JSON output (with --json):

{"event": "uploaded", "file": "hero.png", "attachmentId": 847, "sizeBytes": 142301}
{"event": "replaced", "file": "logo.webp", "attachmentId": 123, "sizeBytes": 8420}
{"event": "file-removed", "file": "old.jpg", "attachmentId": 456, "note": "WordPress attachment not deleted (pass --delete to enable)"}

Low-level Commands

export

Export the full media library (or a filtered subset) as a ZIP archive or directory, preserving the WP uploads directory structure. Includes a manifest.json with full metadata for round-trip re-import.

# Export everything as a ZIP
localpress export --all --to ./backup-2026-05.zip

# Export unoptimized images to a directory
localpress export --unoptimized --to ./to-process/

# Export specific attachments
localpress export 123 456 789 --to ./selected.zip

# Export only JPEGs uploaded since January
localpress export --all --type image/jpeg --since 2026-01-01 --to ./jpegs/

# Export large images (>2MB) with all thumbnail variants
localpress export --all --larger-than 2097152 --include-sizes --to ./large-images/

# Flat export (no year/month subdirectories)
localpress export --all --flat --to ./flat-backup/

# Dry run — see what would be exported
localpress export --all --dry-run

Output structure (directory mode):

backup/
├── manifest.json          # Metadata for all exported items
├── 2026/
│   ├── 01/
│   │   ├── hero.jpg
│   │   └── logo.png
│   └── 05/
│       └── product-shot.webp
└── 2025/
    └── 12/
        └── banner.avif

Manifest format:

{
  "version": 1,
  "site": "production",
  "siteUrl": "https://example.com",
  "exportedAt": "2026-05-10T12:00:00.000Z",
  "items": [
    {
      "id": 123,
      "filename": "hero.jpg",
      "relativePath": "2026/01/hero.jpg",
      "url": "https://example.com/wp-content/uploads/2026/01/hero.jpg",
      "mimeType": "image/jpeg",
      "width": 1920,
      "height": 1080,
      "sizeBytes": 245760,
      "altText": "Hero banner",
      "title": "Hero Image",
      "sha256": "abc123..."
    }
  ],
  "totalBytes": 245760
}

import

Bulk import local files or directories into the WordPress media library, with optional optimization on upload. Reads manifest metadata from a previous export for seamless round-trip workflows.

# Import a directory of product photos with optimization
localpress import ./product-photos/ --optimize --to webp

# Import a previous export, preserving metadata (alt, title, caption)
localpress import ./migration-export/ --preserve-ids

# Import a ZIP from a previous export
localpress import ./backup-2026-05.zip --preserve-ids

# Import with resize constraints
localpress import ./raw-photos/ --optimize --max-width 1920 --max-height 1080

# Import and attach all items to a specific post
localpress import ./gallery/ --post 456

# Import with custom quality and metadata stripping
localpress import ./photos/ --optimize --quality 75 --strip-metadata

# Import with custom title and alt text defaults
localpress import ./icons/ --title "App Icon" --alt "Application icon"

# Dry run — see what would be imported
localpress import ./photos/ --dry-run

Supported file types: .jpg, .jpeg, .png, .webp, .avif, .gif, .svg

Concurrency: Uploads run in parallel (default: CPU cores - 1). Override with --concurrency.

JSON output (with --json):

{
  "action": "imported",
  "site": "production",
  "imported": 42,
  "failures": 1,
  "totalUploadedBytes": 12582912,
  "totalOriginalBytes": 25165824,
  "items": [
    {"file": "hero.jpg", "attachmentId": 847, "filename": "hero.jpg", "sizeBytes": 142301, "optimized": true, "originalSize": 524288}
  ]
}

pull

Download attachments to local disk.

# Download attachments to current directory
localpress pull 123 124

# Download to a specific directory
localpress pull 123 --to ./downloads

# Download with original filename
localpress pull 123 --preserve-filename

push

Upload local files with replace-in-place fallback.

# Upload a local file as a new attachment
localpress push ./optimized.webp

# Upload as a replacement for an existing attachment
localpress push ./optimized.webp --replace 123

# Upload with specific title and alt text
localpress push ./photo.jpg --title "Product Shot" --alt "Red product on white background"

Maintenance Commands

update

Check for new versions and self-update the binary.

# Check for updates and prompt to install
localpress update

# Just check (exit 0 = up-to-date, exit 1 = update available)
localpress update --check

# Auto-install without prompting
localpress update --yes

Detects Homebrew installations and suggests brew upgrade localpress instead of downloading directly. Downloads the correct binary for your platform and does an atomic swap.

JSON output:

{"currentVersion": "1.7.0", "latestVersion": "1.8.0", "updateAvailable": true, "downloadUrl": "...", "releaseUrl": "..."}

completions

Generate shell completion scripts for tab-completion support.

# Bash — append to ~/.bashrc or ~/.bash_profile
localpress completions bash >> ~/.bashrc

# Zsh — save to fpath directory (recommended)
mkdir -p ~/.zsh/completions
localpress completions zsh > ~/.zsh/completions/_localpress
# Then ensure ~/.zshrc contains (before compinit):
#   fpath=(~/.zsh/completions $fpath)
#   autoload -Uz compinit && compinit

# Zsh — alternative: eval in ~/.zshrc
eval "$(localpress completions zsh)"

# Fish — save to completions directory
localpress completions fish > ~/.config/fish/completions/localpress.fish

⚠️ Zsh note: Do NOT append the zsh script directly to ~/.zshrc with >>. The completion script uses zsh completion builtins (_arguments, _describe) that can only run inside the completion system. Use the fpath method or eval instead.

Generates completions for all commands with subcommand-specific options, typed arguments (format choices, model names, sort fields), and shell-idiomatic patterns.

Time-Machine Commands

See the History & Undo guide for the full story; quick reference below.

history

Browse the local snapshot archive — every destructive op is snapshotted before WP mutates.

# List recent sessions
localpress history

# Filter
localpress history --session a1b2c3d4
localpress history --attachment 123
localpress history --operation optimize

# Interactive TUI browser
localpress history -i

# Subcommands
localpress history show <session-prefix-or-snapshot-id>
localpress history prune [--max-size N] [--older-than DAYS] [--max-sessions N]
localpress history clear --yes

undo

Restore from snapshot(s). Defaults to the last session and runs as a dry-run unless --apply is passed. Single-target modes execute immediately.

# Dry-run preview of restoring the last session
localpress undo

# Execute
localpress undo --apply

# Restore a specific session
localpress undo a1b2c3d4 --apply

# Single-target (executes immediately)
localpress undo --snapshot 42
localpress undo --attachment 123

MCP Server Command

mcp

Run as a Model Context Protocol server over stdio. Spawned by an MCP host (Claude Desktop, Cursor, Claude Code, etc.) — not designed for direct human invocation.

# Boot the MCP server (waits on stdin for JSON-RPC messages)
localpress mcp

Exposes 20 tools and 3 resources covering setup, discovery, processing, and library ops. See the dedicated MCP Setup guide for full host configuration instructions and the tool reference.

Host config example (Claude Desktop):

{
  "mcpServers": {
    "localpress": {
      "command": "localpress",
      "args": ["mcp"]
    }
  }
}

Global Flags

All commands support these global flags:

Exit Codes