Skip to content
BranchesTags

Repository files navigation

localpress banner

localpress

GitHub Release Homebrew License: MIT GitHub issues GitHub pull requests Last Commit CI GitHub Sponsors

Your laptop, your library.

Local-compute WordPress management CLI. Optimize media, manage posts and pages, audit accessibility, generate AI alt-text, remove backgrounds — all on your hardware. Syncs to your remote WordPress site via the REST API. No recurring credits. No cloud SaaS. No plugin required.

Website · Docs · Wiki · Releases

localpress in action — doctor check, list media, stats dashboard

localpress interactive media browser — full TUI with sidebar navigation

Install

Homebrew (macOS / Linux)

brew install gfargo/tap/localpress

Pre-built binaries

Download from the releases page. Available for macOS (arm64/x64), Linux (arm64/x64), and Windows (x64).

From source

Requires Bun >= 1.1.0:

git clone https://github.com/gfargo/localpress.git && cd localpress
bun install && bun run dev -- --help

Quick start

# 1. Connect your WordPress site
localpress init

# 2. Audit your media library
localpress audit

# 3. Optimize everything
localpress optimize --unoptimized --apply

# 4. Generate alt text for accessibility
localpress caption --missing-alt --apply

What it does

# Compress images (sharp + jSquash WASM codecs)
localpress optimize 123 124 125
localpress optimize --unoptimized --profile hero --apply

# Convert formats (JPEG → WebP → AVIF)
localpress convert 123 --to webp

# Resize preserving aspect ratio
localpress resize 123 --max-width 1920

# Remove backgrounds with local AI (5 ONNX models including BiRefNet)
localpress remove-bg 123 --model birefnet-lite --preview

# Generate alt text with local Ollama vision model
localpress caption --missing-alt --language Spanish --apply

# Open in GIMP/Photoshop/Preview, save, auto-sync back
localpress edit 123

# Export your entire library for migration
localpress export --all --to ./backup.zip

# Import with optimization on upload
localpress import ./photos/ --optimize --to webp

# Find where an attachment is used
localpress references 1234

# Set metadata directly
localpress metadata 123 --alt "Product photo on white background"

# Watch a directory and auto-push new images
localpress watch ./assets/images --optimize

# Manage posts and pages (including custom post types)
localpress posts list --type portfolio
localpress posts create --title "New Post" --content-file ./draft.html --status draft
localpress posts update 456 --status publish

# Accessibility audit
localpress a11y

# CI budget gate: fail if unoptimized media exceeds 50 MB
localpress audit --json --max-unoptimized-bytes 50000000

CI budget gate

Use --max-unoptimized-bytes <bytes> to gate a CI job on media quality. The command exits 0 when total unoptimized bytes are within budget and exits 7 (BudgetExceeded) when over.

# .github/workflows/media-budget.yml
name: Media budget gate

on:
  schedule:
    - cron: '0 6 * * 1'   # every Monday at 06:00 UTC
  workflow_dispatch:

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - name: Install localpress
        run: brew install gfargo/tap/localpress

      - name: Configure site
        run: |
          localpress init --name production \
            --url "${{ secrets.WP_URL }}" \
            --username "${{ secrets.WP_USERNAME }}" \
            --app-password "${{ secrets.WP_APP_PASSWORD }}"

      # Fails the step (exit 7) when unoptimized media exceeds 50 MB.
      # Remove --json to get a human-readable report instead.
      - name: Media budget gate (50 MB)
        run: localpress audit --json --max-unoptimized-bytes 50000000

Exit code 7 causes the step (and therefore the job) to fail, surfacing the overage in your PR checks or scheduled run. Combine with --all-sites to gate across every configured site at once.

39+ commands

Category Commands
Setup init, sites, doctor, config
Discovery list, show, stats, audit, references, briefing
Processing optimize, convert, resize, remove-bg, caption, metadata
AI Vision title, describe, classify, tag, vision, rename
Content posts list/show/create/update/delete
Accessibility a11y
Migration export, import
Automation watch
Server-side regenerate
Round-trip edit
Low-level pull, push, delete
Time-machine history, undo
Maintenance update, completions

All commands accept --json for machine-readable output and --help for usage details.

AI agent integration (MCP)

localpress ships a built-in Model Context Protocol server with 47+ typed tools. Add it to any MCP host:

// Claude Desktop, Cursor, VS Code, Kiro, etc.
{
  "mcpServers": {
    "localpress": { "command": "localpress", "args": ["mcp"] }
  }
}

Kiro (.kiro/settings/mcp.json, workspace-scoped):

{
  "mcpServers": {
    "localpress": {
      "command": "localpress",
      "args": ["mcp"],
      "autoApprove": ["sites_list", "doctor", "list", "stats", "show", "audit", "site_briefing"]
    }
  }
}

autoApprove lists read-only tools Kiro can call without a per-call confirmation prompt. WordPress credentials live in localpress's own config (localpress init), never in this file — there's nothing to reference via an env var here.

The agent gets typed schemas for every operation — optimize, caption, posts CRUD, accessibility audit, remove-bg, export/import, delete, undo, site briefing, and more.

Structured JSON results, capability discovery via resources, and concurrency control on all bulk operations.

A markdown skill (skill/SKILL.md) is also available for agents that prefer shelling out to the CLI directly.

Kiro Birthday Challenge — site_briefing

Built for Kiro's birthday-week "Custom MCP Integration" challenge: site_briefing is a new MCP tool that answers "what does my WordPress site need today?" in one call. It aggregates every check localpress already knows how to run — unoptimized images, missing alt text, broken content references, orphaned media, and accessibility issues — into a structured summary, then synthesizes a short plain-English triage with a local Ollama text pass (no cloud API). Ask Kiro "what does my WordPress site need today?" and it calls site_briefing against a real site and reports back in plain English instead of you running five separate audits yourself.

Key behaviors

  • Safe by default — bulk ops (--all, --unoptimized) dry-run unless --apply is passed. Explicit IDs execute immediately.
  • Idempotent — re-running optimize on an already-processed attachment is a no-op (SHA-256 hash comparison).
  • Always undoable — every destructive op snapshots the original. Restore with localpress undo.
  • Named profiles — localpress config set-profile hero --quality 75 --format webp --max-width 1920 then optimize --profile hero.
  • Replace-in-place — tries WP-CLI over SSH first, falls back gracefully. --strict fails instead of falling back.
  • Two encoders — sharp (default, native libvips) or jSquash WASM codecs (--encoder jsquash) for OxiPNG-level PNG compression.
  • Multilingual captions — caption --language French generates alt text in any language the Ollama model supports.
  • Posts & pages — full CRUD for posts, pages, and custom post types. Create drafts, publish, update content, manage categories/tags.
  • Accessibility audit — a11y checks heading hierarchy, generic link text, missing img alt, and empty links across all published content.
  • Site briefing — briefing (and the site_briefing MCP tool) rolls up every check above into one summary plus a plain-English Ollama narrative, cached per-site for fast repeat calls (--fresh forces a live re-scan).

Architecture

┌──────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│  MCP Server (47+ │───▶│  localpress CLI  │───▶│  Remote WP site │
│  tools) / Skill  │    │  (TS + Bun)      │    │  (REST / SSH)   │
└──────────────────┘    └──────────────────┘    └─────────────────┘
                                │
                        ┌───────┴────────┐
                        │  Engine layer  │
                        │  sharp/jsquash │
                        │  ONNX Runtime  │
                        │  Ollama vision │
                        │  SQLite state  │
                        └───────┬────────┘
                        ┌───────┴────────┐
                        │ Adapter layer  │
                        │ REST | WP-CLI  │
                        └────────────────┘

Background removal models

Model Size Quality License
birefnet-lite ~224 MB State-of-the-art MIT
isnet-general-use ~176 MB Great edges Apache-2.0
u2net (default) ~176 MB General purpose Apache-2.0
silueta ~44 MB Balanced MIT
u2netp ~4.7 MB Fast Apache-2.0

Models download on first use. Use --preview to adjust in the browser before applying. Or pass --rembg to use system Python rembg instead.

Alt-text generation

Requires Ollama running locally with a vision model:

ollama pull moondream    # ~1.7 GB, fast
localpress caption --missing-alt --apply

No cloud API. No credits. No data leaves your machine. Supports --language for non-English output and --model to choose between installed vision models.

Development

bun install              # install deps
bun run dev -- --help    # run CLI from source
bun run typecheck        # tsc --noEmit
bun run lint             # biome check
bun test                 # 191+ unit tests + integration
bun run build:all        # build tarballs for all 5 platforms

Links

License

MIT. See LICENSE.

About

Local-compute WordPress media optimization CLI. Compress, convert, remove backgrounds, generate alt-text — all on your hardware. No cloud, no credits, no plugin required.

localpress.griffen.codes/

Topics

accessibilityaialt-textavifbackground-removalbunclihomebrewimage-compressionmcpmedia-optimizationollamasharptypescriptwebpwordpress

Resources

Readme
MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Contributors

Languages