# Localwp Shell

> Run wp/php/mysql/composer through LocalWP's sandboxed environment when inside a LocalWP site — fixes 'command not found', wrong PHP version, opcache/xdebug load failures, MySQL socket errors.

- **Type:** Skill
- **Install:** `agentstack add skill-jtsternberg-claude-plugins-localwp-shell`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [jtsternberg](https://agentstack.voostack.com/s/jtsternberg)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [jtsternberg](https://github.com/jtsternberg)
- **Source:** https://github.com/jtsternberg/claude-plugins/tree/main/plugins/localwp-shell/skills/localwp-shell

## Install

```sh
agentstack add skill-jtsternberg-claude-plugins-localwp-shell
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# LocalWP Shell

> **Platform:** macOS only.

Run commands through LocalWP's sandboxed environment (PHP, MySQL, WP-CLI, Composer). Auto-detects the correct LocalWP site from the current working directory, including through symlinked `app/public` directories **and project directories whose contents symlink into a site tree** (e.g. `myproject/links/theme -> ~/Sites/wp-site/wp-content/themes/x` — the script follows the project's symlinks, finds the site, and runs commands from its WordPress root).

## Usage

All scripts live in this skill's directory. Resolve that directory at every independent shell block, then run them with `bash`:

```bash
# Codex: this path resolves under Claude Code; substitute the directory containing this SKILL.md.
SKILL_DIR="${CLAUDE_SKILL_DIR}"

# WP-CLI (most common) — silent by default
bash "$SKILL_DIR/scripts/wplocal" plugin list
bash "$SKILL_DIR/scripts/wplocal" search-replace 'old.test' 'new.test'
bash "$SKILL_DIR/scripts/wplocal" db export backup.sql

# PHP, Composer, MySQL — full env with version info
bash "$SKILL_DIR/scripts/localwpshell" php -v
bash "$SKILL_DIR/scripts/localwpshell" composer install
bash "$SKILL_DIR/scripts/localwpshell" mysql -e "SHOW DATABASES;"

# Silent mode — only command output, no env info
bash "$SKILL_DIR/scripts/silentlocalwpshell" php -r 'echo PHP_VERSION;'
```

### Commands

| Command | Purpose |
|---------|---------|
| `$SKILL_DIR/scripts/localwpshell [cmd]` | Load LocalWP env, show versions, optionally run a command |
| `$SKILL_DIR/scripts/silentlocalwpshell [cmd]` | Same as above but suppresses info output |
| `$SKILL_DIR/scripts/wplocal [wp-args]` | Shorthand for `silentlocalwpshell wp ...` |

## When to Use

**Always wrap commands through these scripts when the working directory is inside a LocalWP site.** The system PHP/MySQL on macOS is not the same as what LocalWP provisions.

### Recognizing a LocalWP Site

- The path contains `Local Sites/`
- The path is inside a symlinked LocalWP directory (handled automatically)
- The project has the typical LocalWP structure: `app/public/wp-content/`
- The project directory contains symlinks INTO a LocalWP site (handled automatically — searched up to 2 levels deep)

## Critical Warnings

**NEVER source a LocalWP ssh-entry script directly** (`source "~/Library/Application Support/Local/ssh-entry/XXX.sh"`). It launches an interactive shell that blocks the agent indefinitely. Always go through `localwpshell` / `silentlocalwpshell` / `wplocal`, which extract the environment without spawning a shell.

**WordPress Multisite: always pass `--url=`.** On a multisite install, WP-CLI without `--url` targets the network's primary site — pages, options, and plugin changes land on the WRONG site silently. Find the right URL first (`wp site list`), then include it in every command:

```bash
# Codex: this path resolves under Claude Code; substitute the directory containing this SKILL.md.
SKILL_DIR="${CLAUDE_SKILL_DIR}"
bash "$SKILL_DIR/scripts/wplocal" site list
bash "$SKILL_DIR/scripts/wplocal" post list --post_type=page --url=https://wp.wpengine/coaching
```

### Error Patterns That Mean "Use This Skill"

- `Error: Failed loading /opt/...opcache.so` or `xdebug.so` — wrong PHP binary
- `ERROR 2002 (HY000): Can't connect to local MySQL server through socket` — wrong MySQL
- `PHP Fatal error: Uncaught Error: Call to undefined function ...` — missing PHP extension
- `wp: command not found` — WP-CLI not on PATH
- PHP version mismatch (e.g. expecting 8.x, got system 7.x)
- Composer dependency conflicts due to wrong PHP version

### Recovery

```bash
# Codex: this path resolves under Claude Code; substitute the directory containing this SKILL.md.
SKILL_DIR="${CLAUDE_SKILL_DIR}"
# Instead of:        Use:
wp plugin list       bash "$SKILL_DIR/scripts/wplocal" plugin list
php -v               bash "$SKILL_DIR/scripts/localwpshell" php -v
composer install     bash "$SKILL_DIR/scripts/localwpshell" composer install
```

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [jtsternberg](https://github.com/jtsternberg)
- **Source:** [jtsternberg/claude-plugins](https://github.com/jtsternberg/claude-plugins)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-jtsternberg-claude-plugins-localwp-shell
- Seller: https://agentstack.voostack.com/s/jtsternberg
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.