# elementor-cli

CLI and MCP server for reading and writing [Elementor](https://elementor.com/) page data on WordPress.

## Installation

```bash
npm install -g elementor-cli
# or run without installing:
npx elementor-cli <command>
```

## Credentials

Create a `.elementor-cli.env` file (or export variables in your shell):

```bash
cp .elementor-cli.env.example .elementor-cli.env
# Edit with your WordPress URL and application password
```

Generate an application password: **WordPress Admin → Users → Profile → Application Passwords**.

Environment variables:

| Variable          | Description                                   |
|-------------------|-----------------------------------------------|
| `WP_URL`          | Full URL of your WordPress site               |
| `WP_USER`         | WordPress username                            |
| `WP_APP_PASSWORD` | Application password (spaces are fine)        |
| `WP_PATH`         | WordPress root on the server (SSH mode only, default `/var/www/html`) |

## Commands

### Connection

```bash
elementor connection test
```

### Pages

```bash
# List all Elementor pages
elementor pages list
elementor pages list --status draft
elementor pages list --format json

# Show element tree for a page
elementor pages get 42
elementor pages get 42 --format json

# Search elements by text content
elementor pages search 42 "Welcome"

# Find and replace text across a page
elementor pages replace 42 "Old Company" "New Company"
elementor pages replace 42 "Old" "New" --dry-run

# Restore from backup
elementor pages restore 42
elementor pages restore 42 --backup .elementor-backups/42-2024-01-01T12-00-00.json
```

### Widgets

```bash
# Inspect a widget's settings
elementor widgets get 42 abc123
elementor widgets get 42 widget:heading[0] --format json

# Update widget settings (key=value pairs)
elementor widgets set 42 abc123 title="New Heading"
elementor widgets set 42 abc123 title="Hello" header_size=h1 --dry-run
```

### SSH+WP-CLI transport

For servers that restrict REST API access, use SSH+WP-CLI:

```bash
elementor pages list --ssh user@yourserver.com
elementor widgets set 42 abc123 title="Hello" --ssh user@yourserver.com
```

## Claude Code MCP Integration

Add the MCP server so Claude Code can call commands autonomously:

```bash
elementor mcp config
```

Paste the output into your Claude Code `mcp.json` (or `~/.config/claude/mcp.json`):

```json
{
  "mcpServers": {
    "elementor-cli": {
      "command": "npx",
      "args": ["elementor-cli", "mcp", "serve"],
      "env": {
        "WP_URL": "${WP_URL}",
        "WP_USER": "${WP_USER}",
        "WP_APP_PASSWORD": "${WP_APP_PASSWORD}"
      }
    }
  }
}
```

Available MCP tools: `elementor_connection_test`, `elementor_pages_list`, `elementor_pages_get`, `elementor_pages_search`, `elementor_pages_replace`, `elementor_pages_restore`, `elementor_widgets_get`, `elementor_widgets_set`.

## Schema

The committed `src/schema/elementor-schema.json` covers the **free Elementor plugin** widgets only (GPL-licensed, safe to redistribute).

**Elementor Pro users:** place your `./plugins/elementor-pro/` directory in the project root and run:

```bash
npm run update-schema
```

This regenerates the schema locally with Pro widget support. The `./plugins/` directory is gitignored — Pro source is never committed.

## Development

```bash
npm install
npm run typecheck
npm test
npm run lint
```