PHPackages                             vdrnn/acorn-sync - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [CLI & Console](/categories/cli)
4. /
5. vdrnn/acorn-sync

ActiveLibrary[CLI & Console](/categories/cli)

vdrnn/acorn-sync
================

WordPress environment synchronization commands for Acorn

015PHP

Since Jan 20Pushed 3mo agoCompare

[ Source](https://github.com/vdrnn/sync-script)[ Packagist](https://packagist.org/packages/vdrnn/acorn-sync)[ RSS](/packages/vdrnn-acorn-sync/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependenciesVersions (1)Used By (0)

Acorn Sync
==========

[](#acorn-sync)

WordPress environment synchronization for Bedrock and Radicle projects. Sync databases and uploads between development, staging, and production environments via WP-CLI.

> **Note**: This package is heavily inspired by and based on the original [roots/sync-script](https://github.com/roots/sync-script/) bash script, reimplemented as an Acorn package with Laravel-style configuration and improved cross-platform support.

Features
--------

[](#features)

- 🔄 **Database sync** - Export, import, and search-replace URLs between environments
- 📁 **Uploads sync** - Transfer media files via rsync with progress indicators
- 🌐 **Multi-environment** - Manage development, staging, and production setups
- ⚙️ **WP-CLI integration** - Auto-manages aliases and remote command execution
- 🤖 **Auto-detection** - Reads existing wp-cli.yml configuration
- 🔌 **SSH port support** - Works with custom ports (Kinsta, managed hosting)
- 📊 **Status monitoring** - Check environment connectivity before syncing
- 🎛️ **Configuration CLI** - View and edit settings via command line
- 🔔 **Slack notifications** - Optional sync completion alerts
- 🛡️ **Safety first** - Confirmation prompts and automatic backups
- 🌊 **Local dev friendly** - Compatible with Valet, DDEV, and similar tools

Installation
------------

[](#installation)

Install via Composer:

```
composer require vdrnn/acorn-sync
```

Clear Acorn cache to register the commands:

```
wp acorn optimize:clear
```

Quick Start
-----------

[](#quick-start)

1. **Initialize the package:**

    ```
    wp acorn sync:init --auto
    ```

    This will automatically detect your wp-cli.yml and set up environments.
2. **Review and adjust paths (if needed):**Edit `.env` to fix uploads paths for your specific deployment (see [Setup Workflow](#setup-workflow)).
3. **Check environment connectivity:**

    ```
    wp acorn sync:status
    ```
4. **Sync from production to development:**

    ```
    wp acorn sync:env production development
    ```

Migrating from sync.sh
----------------------

[](#migrating-from-syncsh)

If you're currently using the original [roots/sync-script](https://github.com/roots/sync-script/) bash script, Acorn Sync can automatically migrate your configuration!

**How it works:**

1. Run `wp acorn sync:init --auto --force`
2. The package will automatically:
    - ✅ Detect your existing `sync.sh` file (searches project recursively)
    - ✅ Parse URLs and uploads paths from the script
    - ✅ Merge with `wp-cli.yml` SSH configuration
    - ✅ Generate Laravel-style configuration files
    - ✅ Safely backup `sync.sh` to `sync.sh.backup`

**What gets migrated:**

- `DEVSITE`, `STAGSITE`, `PRODSITE` → Environment URLs
- `DEVDIR`, `STAGDIR`, `PRODDIR` → Uploads paths
- Slack webhook URLs (if configured)

**Smart merging:**

- SSH/remote paths come from `wp-cli.yml` (more reliable)
- URLs and uploads come from `sync.sh` (if different from auto-detected paths)
- You get the best of both configurations!

Setup Workflow
--------------

[](#setup-workflow)

### Recommended Process

[](#recommended-process)

1. **Ensure `wp-cli.yml` is configured** (for WP-CLI remote access):

    ```
    @production:
      ssh: 'user@host:/path/to/project'
      path: web/wp
    ```
2. **Run auto-detection**:

    ```
    wp acorn sync:init --force --auto
    ```

    This will:

    - ✅ Read your `wp-cli.yml` and detect all environments
    - ✅ Generate `config/sync.php` with `env()` helpers
    - ✅ Populate `.env` with auto-detected paths
    - ✅ Update `wp-cli.yml` with aliases (if needed)
3. **Review generated `.env` file**:

    ```
    # Check the generated paths
    grep "SYNC_" .env
    ```
4. **Adjust uploads paths for your deployment**:

    **Standard structure** (auto-detected):

    ```
    SYNC_PRODUCTION_UPLOADS_PATH="user@host:/path/to/project/web/app/uploads/"
    ```

    **Ploi/Trellis deployments** (need manual update):

    ```
    # Update to shared directory
    SYNC_PRODUCTION_UPLOADS_PATH="user@host:/path/to/project-shared/uploads/"
    ```
5. **Verify connectivity**:

    ```
    wp acorn sync:status
    ```

### Key Points

[](#key-points)

- **wp-cli.yml** = WP-CLI configuration (SSH access to WordPress)
- **.env** = Sync package configuration (uploads paths, URLs, etc.)
- **Auto-detection gives a good starting point** - fine-tune in `.env` for your deployment
- **No need to manually edit wp-cli.yml** - `sync:init` handles it
- **Different deployments use different paths**:
    - Standard: `/project/web/app/uploads/`
    - Ploi: `/project-shared/uploads/`
    - Trellis: `/project/shared/uploads/`
    - Custom hosting: Adjust based on your structure

### Why Edit .env?

[](#why-edit-env)

Auto-detection assumes standard Bedrock structure, but many hosting providers (Ploi, Trellis) use shared directories for uploads that persist across deployments. The `.env` file lets you override these paths without modifying committed config files.

Commands
--------

[](#commands)

### `sync:init`

[](#syncinit)

Initialize Acorn Sync configuration with interactive prompts.

```
wp acorn sync:init [--force] [--auto]
```

**Options:**

- `--force` - Overwrite existing configuration
- `--auto` - Auto-detect configuration from existing wp-cli.yml

### `sync:env`

[](#syncenv)

Sync data between WordPress environments.

```
wp acorn sync:env {from} {to} [options]
```

**Arguments:**

- `from` - Source environment (development, staging, production)
- `to` - Target environment (development, staging, production)

**Options:**

- `--skip-db` - Skip database synchronization
- `--skip-assets` - Skip assets synchronization
- `--local` - Use local WP-CLI for development environment
- `--no-slack` - Skip Slack notification
- `--no-permissions` - Skip setting upload permissions
- `--force` - Skip confirmation prompts

**Examples:**

```
# Sync everything from production to development
wp acorn sync:env production development

# Sync only database from staging to development
wp acorn sync:env staging development --skip-assets

# Sync only assets from development to staging
wp acorn sync:env development staging --skip-db

# Force sync without confirmation
wp acorn sync:env production development --force
```

### `sync:status`

[](#syncstatus)

Check environment connectivity and configuration status.

```
wp acorn sync:status [environment]
```

**Examples:**

```
# Check all environments
wp acorn sync:status

# Check specific environment
wp acorn sync:status production
```

### `sync:config`

[](#syncconfig)

Manage Acorn Sync configuration.

```
wp acorn sync:config [action] [--environment=]
```

**Actions:**

- `show` - Display current configuration (default)
- `edit` - Edit configuration interactively
- `reset` - Reset configuration to defaults

**Examples:**

```
# Show all configuration
wp acorn sync:config

# Show specific environment configuration
wp acorn sync:config show --environment=production

# Edit configuration interactively
wp acorn sync:config edit

# Reset configuration
wp acorn sync:config reset
```

Configuration
-------------

[](#configuration)

The package uses a configuration file at `config/sync.php`. Here's an example:

```