wp acf json sync

Documentation wp acf json sync

Last updated Mar 30, 2026

Overview

Syncs local JSON changes to the database.

Description

Imports pending JSON changes for ACF item types (field groups, post types, taxonomies, options pages). This command reads JSON files from your theme/plugin acf-json directory and creates or updates the corresponding database entries.

Warning: This command modifies your database. Use --dry-run first to preview changes before running on production.

Options

wp acf json sync [--type=<type>] [--key=<key>] [--dry-run]

--type=<type> (string) Optional. Limit sync to a specific item type. Defaults to all item types (field groups, post types, taxonomies, options pages). – field-group – post-type – taxonomy – options-page (ACF PRO only)

--key=<key> (string) Optional. Sync a specific item by its ACF key (e.g., group_abc123).

--dry-run (flag) Optional. Preview what would be synced without making changes. Recommended for production deployments.

Examples

Preview what will be synced (safe)

$ wp acf json sync --dry-run
3 item(s) pending sync:
+-------------------+------------------+---------------+--------+
| Key               | Title            | Type          | Action |
+-------------------+------------------+---------------+--------+
| group_abc123      | Product Fields   | field-group   | Update |
| group_def456      | Homepage         | field-group   | Create |
| taxonomy_ghi789   | Product Category | taxonomy      | Update |
+-------------------+------------------+---------------+--------+

Sync all pending changes

$ wp acf json sync
Updated field-group: Product Fields (group_abc123)
Created field-group: Homepage (group_def456)
Updated taxonomy: Product Category (taxonomy_ghi789)
Success: 3 item(s) synced.

Sync only field groups

$ wp acf json sync --type=field-group

Sync a specific field group

$ wp acf json sync --key=group_abc123
Updated field-group: Product Fields (group_abc123)
Success: 1 item(s) synced.

CI/CD deployment workflow

# Preview changes
$ wp acf json sync --dry-run

# Apply changes
$ wp acf json sync

# Verify sync completed
$ wp acf json status

Notes

• Always run --dry-run first on production environments
• The sync command replicates the “Sync” functionality in the WordPress admin
• Items marked as private are skipped
• If no items are pending, the command outputs “Everything is already in sync.”
• Options pages require ACF PRO

Related

• CLI: wp acf json status
• CLI: wp acf json import
• CLI: wp acf json
• CLI: wp acf json export
• Features: Local JSON