Import, export and sync

01Overview

Nucleo stores the JSON document of each page in the post metadata and the site configuration in WordPress options. The precomputed data for the front end ("artifacts") live in PHP files under wp-content/uploads/nucleo/store/, or in options if the folder is not writable. The export turns the site into a map "relative path → JSON text": site.json, pages/, posts/, layouts/, sections/, menus/, media/manifest.json, rules/assets.json, content/ and terms/ for the modeled types and taxonomies. The import reads the same map and creates or updates each document by post type and slug, and each item and term by slug. site.json contains a fingerprint (base) of each document at the time of the export: the import uses it to detect the changes made on the site in the meantime. Three surfaces use the same engine: the abilities nucleo/site-export and nucleo/site-import, the WP-CLI commands wp nucleo export|import|sync, and the Tools screen. The local CLI nucleo pull and nucleo push call the abilities via REST and add the image upload (media/).

02Storage

Document and history in the post metadata

What it does: saves the source document, the revision number, the runtime index and the history of the latest versions in the post metadata.

How to use it: internal. The save pipeline uses it for every document write.

Parameters:

The compiled HTML goes into post_content. The compiled CSS of the blocks goes into uploads/nucleo/css/.

Permissions: depend on the ability or the command that saves.

Edition: Free

Known limits: the history keeps 20 versions. Restore returns the document of a revision but does not save it: the caller decides (see nucleo/doc-rollback in the write abilities).

Site options

What it does: keeps the Nucleo configuration in the options table.

How to use it: internal. The design and administration abilities write these options.

Parameters: options relevant for import and export.

The WordPress settings exported in site.json (blogname, blogdescription, show_on_front, page_on_front, page_for_posts, date_format, time_format, language) stay in the native options.

Permissions: depend on the ability or the command that writes.

Edition: Free

Known limits: none found.

Artifact store

What it does: saves precomputed PHP arrays that the front end reads on every request: tokens, layout map, compiled layouts, asset rules, content model and critical CSS.

How to use it: internal. The store uses the folder wp-content/uploads/nucleo/store. The active driver appears in nucleo/status and in the "System status" panel of the Tools screen.

Parameters: two drivers.

Nucleo chooses php-file if the folder exists or can be created and is writable. Otherwise it chooses option. Keys used: tokens, layouts, layout-<id>, asset-rules, content-model, critical and the state of the CSS optimizer.

Permissions: none: the store is not exposed.

Edition: Free

Known limits: keys must match /^[a-z0-9][a-z0-9_-]{0,63}$/. Values accept only scalars, null and nested arrays: objects, resources, NAN and INF cause an error. An unreadable file counts as a missing artifact.

Store generation and rebuild

What it does: separates the artifact files of each database. After a reset or a database import, the generation in the option is missing. Nucleo then does not read the old files and rebuilds the artifacts from the database.

How to use it: automatic. When the administration area starts (admin_init), Nucleo creates the generation if it is missing and rebuilds the store if tokens or layouts are missing. The first write without a generation creates it too. The ability nucleo/cache-rebuild rebuilds the store without recompiling the documents.

Parameters: the generation is an identifier of 10 hexadecimal characters (5 random bytes) in nucleo_store_generation. The accepted format is /^[a-z0-9]{1,16}$/.

• On the main site, when the generation is created, Nucleo moves the files of the base folder into the new folder if the database has Nucleo data (documents, layouts or content model). Without data, it deletes them.
• Then it deletes the other generations of the same blog.
• The rebuild republishes tokens, asset rules, layouts and the content model. With the recompile option it also queues the recompilation of all the documents.

Permissions: the check in admin_init runs for every user who opens the dashboard. nucleo/cache-rebuild requires manage_options and the scope nucleo:admin.

Edition: Free

Known limits: the rebuild uses a lock of 300 seconds: a second request returns false. A filesystem error in admin_init is ignored and the next request tries again. The front end never rebuilds the store.

Audit log

What it does: records every write of the abilities with user, OAuth client, ability, post, result and summary. nucleo/site-import writes one row per call with summary import or dry-run.

How to use it: internal. Read with nucleo/audit-list.

Parameters: table {prefix}nucleo_audit with columns id, time, user_id, client_id, ability, post_id, ok, summary.

Permissions: depend on the ability that reads.

Edition: Free

Known limits: keeps the latest 10,000 rows. Cleanup runs every 100 inserts. ability is truncated to 64 characters, summary to 255. Reading returns at most 1,000 rows.

03Export package

File structure

What it does: defines the files produced by the export. Each value is JSON text with indentation, slashes and Unicode not escaped.

How to use it: produced by nucleo/site-export, wp nucleo export, the Tools screen (zip) and nucleo pull.

Parameters:

Only the posts of the four types that have a Nucleo document are exported, with status any, in ID order. The file slug is post_name. A draft without a slug uses the slug generated from the title, or post-<ID>.

Permissions: see nucleo/site-export.

Edition: Free

Known limits: two posts with the same path (same type and same slug) produce one file: the one with the higher ID wins. A child page uses only its own slug in the file name: two child pages with the same name and different parents collide. Pages in another language with the same slug collide in the same way. With a multilingual site the result is not verified: the path does not distinguish the language. Items with managedBy are not exported to content/: they stay in pages/ or posts/.

site.json

What it does: carries the global configuration and the fingerprints for conflict checks.

How to use it: edit it locally and send it back with the import. After a successful push the CLI updates the keys base, tokensBase and siteBase.

Parameters:

homepage and postsPage are the slug (or the path, for a child page) of the page. homepage is null if the home shows the latest posts.

Permissions: see nucleo/site-import.

Edition: Free

Known limits: breakpoints is informational only: the import does not apply it.

Document files

What it does: contains the Nucleo document (see the schema of the document and the blocks) plus the wp block with the WordPress data.

How to use it: {"schema": 1, "kind": ..., "meta": {...}, "root": {...}, "wp": {...}}.

Parameters: keys of the wp block.

Symbolic references: the export replaces the IDs with readable names and the import converts them back.

Permissions: see nucleo/site-import.

Edition: Free. lang and translations require the Pro package with a multilingual plugin. Nucleo checks the presence of the multilingual component, not the license.

Known limits: an ID without a name stays numeric. It happens for custom post type posts in the conditions and for deleted objects. A media URL outside the manifest (for example a reduced size -300x200) stays absolute. At import an unresolved symbol gives "Unresolved symbol: …".

menus/<slug>.json

What it does: exports a WordPress menu with its items. The file name is the menu slug.

How to use it: {"name": "...", "items": [{"label", one of page | post | ref | url, "children"?}]}. ref accepts <post-type>:<slug>, term:<taxonomy>/<slug>, archive:<post-type> or home.

Parameters: see the full description of the format in nucleo/menu-set.

Permissions: see nucleo/site-import.

Edition: Free

Known limits: the export skips the items whose target is unpublished, deleted or not public. The ability reports them in skipped with menu, label and reason.

Media in the export

What it does: media/manifest.json lists the attachments with status inherit that have a file on disk: file (original file name, not the -scaled copy), url, alt and the sha1 of the file.

How to use it: the export does not include binary files. At import each media:<file> becomes the URL of an attachment of the destination site, in this order:

1. attachment with the same file name and the same sha1;
2. attachment of the site that the item's url points to, if the file has the same sha1;
3. download from the item's url with media_sideload_image.

A name missing from the manifest uses the library attachment with the same file name, whatever its sha1. In the dry-run the URL comes from the manifest, without download.

Parameters: none.

Permissions: see nucleo/site-import.

Edition: Free

Known limits: the download requires that the source site URL is reachable from the destination site and passes the WordPress URL validation. Errors: "Media not found in the manifest or in the library: …", "Invalid media URL: …", "Media not downloaded (…): …". The manifest contains the whole library, not only the attachments in use.

04Export and import

nucleo/site-export

What it does: returns the site as a map of JSON files, including the items of content/ and the terms of terms/ for the modeled types and taxonomies.

How to use it: read ability, GET on /wp-json/wp-abilities/v1/abilities/nucleo/site-export/run, or MCP tool. Empty input. Output {files: {path: text}, skipped: [{menu, label, reason}]}.

Parameters: none.

Permissions: manage_options; OAuth scope nucleo:admin.

Edition: Free

Known limits: no pagination: the response contains all the documents, the items and the full manifest. The export is not a full backup of the site: it does not contain the content model, the Nucleo settings, the per-page settings (_nucleo_page), the fields of the documents and the documents on generic content types. For a backup use a WordPress tool. Annotations: readonly, idempotent.

nucleo/site-import

What it does: imports the files produced by nucleo/site-export. It creates or updates tokens, terms, items, sections, pages, posts, layouts, rules, media, menus and site settings.

How to use it: write ability, POST on /wp-json/wp-abilities/v1/abilities/nucleo/site-import/run, or MCP tool. Example: {"files": {"pages/home.json": "{...}"}, "dryRun": true}.

Parameters:

Output: created, updated, unchanged (integers), errors ([{file, message, code, guide?}]), warnings ([{file, message}]), ids (symbol → ID), base, tokensBase, siteBase. Error codes: error, conflict, duplicate, not_json, invalid_document, quality_blocking, unsupported_status, legacy_base. A code from another service becomes error and stays at the start of the message (for example menu_target_missing: …).

Permissions: manage_options; OAuth scope nucleo:admin. The write rate limit applies here too.

Edition: Free

Known limits: invalid input gives WP_Error invalid_input. An error on one file does not stop the others. tokensBase appears only if the site tokens now match those of site.json. siteBase appears only after a real import with a site block. The dry-run does not return diffs or the full quality report: only counts, errors and warnings. Annotations: not readonly, not destructive, idempotent.

Import order and rules

What it does: describes how the import processes the files.

How to use it: applies to the ability, WP-CLI, the Tools screen and nucleo push.

Parameters: processing order.

1. Each path that does not end in .json gives not_json. A .php file also receives guide with the rule on component code.
2. site.json: reads base, site, siteBase; writes the tokens.
3. media/manifest.json.
4. terms/*.json, then content/<type>/*.json: upsert by slug, in batches of 500 terms and 25 items. The parent comes before its children.
5. menus/*.json: creates or renames menus, without items.
6. sections/, sorted by dependency: a section inserted into another with nc/section-ref comes first.
7. pages/, sorted by wp.parent: the parent comes before its children.
8. posts/, then layouts/.
9. Menu items, when pages and posts exist.
10. rules/assets.json.
11. Languages and translation linking (real import only, Pro package only).
12. Settings of the site block. The language is applied last.

The pages arrive before the layouts: the layout conditions cite the pages.

Rules for documents:

• Search by postType and slug with any status. A found post is updated, otherwise it is created.
• Two files with the same type, slug and language: the second gives duplicate.
• Document, title, status and parent equal to the site: no save, counted in unchanged.
• A section not imported makes the pages that use it fail, with the reason.
• wp.parent on a type other than page, a parent not found or a cycle give an error. A published child with an unpublished parent gives a warning.
• The save goes through the same pipeline as doc-create and doc-patch: schema, blocking quality, acknowledge.
• A file in a folder not listed (for example other/) is ignored without error.

Rules for content/ and terms/:

• The file name must be the item's slug and the folder must be its type; otherwise the item gives an error.
• A slug equal to a document in pages/ or posts/ gives duplicate: the document wins.
• No conflict check in the import: the upsert overwrites items and terms with the same slug. The fingerprints of site.json cover only documents. The check on each item and term is done by the CLI with its base (see nucleo push).

Permissions: those of the surface that calls.

Edition: Free

Known limits: asset rules are replaced entirely. The import never deletes posts, menus, terms, items or entries missing from the files: only wp nucleo sync --prune moves Nucleo documents to trash. The language of the site block may require downloading the package: it needs the permission to install languages, or WP-CLI without a user, and no DISALLOW_FILE_MODS. Without the package the error has code language_unavailable and the other keys stay written.

Conflict check

What it does: compares three ways the local file, the base in site.json and the state of the site. It prevents an import from deleting changes made on the site after the export.

How to use it: automatic when site.json has base, tokensBase or siteBase. Bypassed with force. It does not apply to content/ and terms/ in the import: for those files the CLI compares the base of each item and term (see nucleo push).

Parameters: fingerprints.

• Document: sha1 of the normalized document, of the post title and of the post status, with the prefix v2:. For a child page the fingerprint includes the parent path. A move, a title or a status changed on the site counts as a change of the document. A base without the v2: prefix uses the previous comparison, without title and status.
• Tokens: sha1 of the effective tokens, defaults included.
• Settings: one fingerprint per key of the site block.

A file without an entry in base is not checked: it is imported. A base written before Nucleo 0.3.5 (without the v2: prefix) does not contain title and status: if the file would change them compared to the site, the import stops with legacy_base instead of rewriting them. Solve it with nucleo pull --only <file> or nucleo push --force <file>. For tokens and settings the same table applies. A token conflict gives conflict on site.json. A settings conflict lists the keys involved.

Permissions: those of the surface that calls.

Edition: Free

Known limits: force does not roll back a key of site changed only on the site: the site value stays. The new base returned keeps the old base for the keys in conflict or not written.

Dry-run

What it does: runs the import without writing and returns the same errors per file.

How to use it: dryRun: true in the ability, wp nucleo import --dry-run, nucleo push --dry-run. The Tools screen always runs it as a preview.

Parameters: behavior.

• New tokens in site.json apply to validation through the filter pre_option_nucleo_tokens, without saving them.
• Sections of the same import apply to the pages that insert them.
• A document that cites a symbol created in the same import is counted without being validated and gets a warning in warnings.
• Terms and items of content/ that this import creates count as found for the following documents, menu items and settings.
• New menus and new pages count as found for the following documents, menu items and settings.
• Menu items and site settings go through the same checks as the real import.

Permissions: those of the surface that calls.

Edition: Free

Known limits: a document that cites an object not yet created does not get schema and quality validation. Languages and translations are not checked.

wp nucleo export

What it does: writes the export files to a folder on the server, including content/ and terms/.

How to use it: wp nucleo export <dir> --user=<admin>. Syntax in the WP-CLI commands chapter.

Parameters: <dir> required: without it, the command stops with "Specify the site folder.".

Permissions: a user with manage_options is required: without one, the command stops with an error. Pass --user=<admin>.

Edition: Free

Known limits: does not report skipped menu items. Existing files with the same path are overwritten. Old files no longer exported stay. Absolute paths, paths with .. or with backslashes give an error.

wp nucleo import

What it does: reads recursively the .json files of a folder and imports them.

How to use it: wp nucleo import <dir> [--dry-run] [--force]. Syntax in the WP-CLI commands chapter.

Parameters:

Permissions: a user with manage_options is required (--user=<admin>): without one, the command stops with an error.

Edition: Free

Known limits: prints only "Created, updated, unchanged" and one warning per error. Does not print the warnings. Does not update the base of site.json. Does not accept acknowledge: a document with blocking signals fails. Does not accept force per single file.

wp nucleo sync

What it does: imports the folder like wp nucleo import. With --prune it moves to trash the Nucleo documents that no longer have a file.

How to use it: wp nucleo sync <dir> [--prune]. Syntax in the WP-CLI commands chapter.

Parameters:

Permissions: a user with manage_options is required (--user=<admin>): without one, the command stops with an error.

Edition: Free

Known limits: no --dry-run and no --force. The prune compares the files of the folder, not the result of the import: a file with an error still protects its post.

Tools screen: export and import zip

What it does: downloads the export as a zip and imports a zip or .json files with a preview.

How to use it: dashboard, Nucleo AI → Tools (slug nucleo-tools).

• "Download zip" runs nucleo/site-export and downloads nucleo-export-YYYY-MM-DD.zip, without compression.
• The "Import the site" box accepts a single .zip or one or more .json files. It runs nucleo/site-import at once with dryRun: true and shows the preview.
• "Import" runs the real import. The checkbox "Overwrite changes made on the site" asks for confirmation and sends force: true.

Parameters: none.

Permissions: screen with the manage_options capability. The abilities require manage_options.

Edition: Free

Known limits:

• The zip must have uncompressed (method 0) and unencrypted entries. A zip created by another tool with compression gives an error.
• The .json files chosen one by one arrive with the file name only, without folder: home.json instead of pages/home.json. The import ignores them, except site.json.
• No field for acknowledge and no force per single file.

05Sync with the local CLI

Local folder

What it does: represents the site on disk. The default folder is nucleo-site in the current directory.

How to use it: created with nucleo pull, edited, sent with nucleo push. Syntax and configuration (--site, --user, --password, Application Password) in the local CLI chapter.

Parameters: structure.

nucleo-site/
├── site.json
├── pages/<slug>.json
├── posts/<slug>.json
├── layouts/<slug>.json
├── sections/<slug>.json
├── menus/<slug>.json
├── media/manifest.json
├── media/<image>            (push only: uploaded with nucleo/media-upload)
├── rules/assets.json
├── content/<type>/<slug>.json
├── terms/<taxonomy>.json
└── .nucleo-backup/          (backup copies made by pull)

Permissions: see the individual functions.

Edition: Free

Known limits: absolute paths, paths with .., ., empty segments or backslashes are rejected before writing.

nucleo pull

What it does: downloads the site into the local folder.

1. Calls nucleo/site-export and writes all the files returned.
2. Downloads the content items into content/<type>/<slug>.json with nucleo/content-list (full: true, 50 per page).
3. Downloads the terms into terms/<taxonomy>.json with nucleo/terms-get.

How to use it: nucleo pull [dir] [--prune] [--only FILE[,FILE]].

Parameters:

What it downloads into content/ and terms/:

• A type is downloaded if it is in the content model (modeled: true) or if the folder content/<type> already exists.
• A taxonomy is downloaded if it is in the model or if terms/<taxonomy>.json already exists.
• Items with managedBy (they have a Nucleo document) are not written to content/: they stay in pages/ or posts/.
• Without --prune, local files missing from the site stay and appear as "local only". Local terms missing from the site stay at the end of the file.

Permissions: nucleo/site-export requires manage_options (scope nucleo:admin). nucleo/content-list requires edit_posts or the edit_posts capability of the type (scope nucleo:read). nucleo/terms-get requires edit_posts and assign_terms of the taxonomy (scope nucleo:read).

Edition: Free

Known limits: a missing content-list or terms-get ability (HTTP 404) is skipped. An item without a slug, or skipped by the server, gives a warning on stderr. Menu items skipped by the export give a warning. Calls to content-list and terms-get with rate_limited are repeated up to 5 times after retryAfter seconds (10 if missing). The site-export call is not repeated.

nucleo pull --only

What it does: rewrites only the indicated files and their entry in base. It serves to resolve a conflict by keeping the site version.

How to use it: nucleo pull --only pages/home.json or --only site.json.

Parameters: list of paths present in the response of nucleo/site-export.

• Before overwriting, each local file with different content goes to <dir>/.nucleo-backup/<date-time>/<path>.
• Without site.json in the list: in the local site.json only the base entries of the chosen files change. The other keys stay.
• With site.json in the list: the site's site.json is written, with the base of the local site.json.

Permissions: manage_options; scope nucleo:admin.

Edition: Free

Known limits: rejects content/ and terms/. Rejects a path missing from the export. Does not use --prune. Reads happen before every write: an error does not leave half-written files.

nucleo push

What it does: sends the local folder to the site, in this order.

1. Uploads the images of media/ with nucleo/media-upload and updates media/manifest.json.
2. Sends terms/ with nucleo/terms-set (batches of 500) and content/ with nucleo/content-upsert (batches of 25).
3. Sends the rest of the folder to nucleo/site-import.
4. After a real push it writes the new base, tokensBase and siteBase into site.json, and the base of the items and terms of each accepted batch, even if the push fails later.

How to use it: nucleo push [dir] [--dry-run] [--prune] [--yes] [--use-tokens] [--acknowledge FILE] [--force FILE[,FILE]].

Parameters:

What does not go to site-import: content/, terms/, .nucleo-backup/ and the consent file if it is in the folder. Only .json files are read. Before sending anything, the command reads and validates the whole folder: pages and other JSON files, content/, terms/ and media/manifest.json. A local error stops the push without changes on the site.

Rules for content/:

• The file slug must match slug and the folder must match type, if present. Otherwise the error slug_mismatch or type_mismatch.
• A slug also present in pages/ (type page) or posts/ (type post) gives duplicate: the document wins.
• Parents arrive before children. A type that cites <other type>:<slug> in fields arrives after the type cited.
• The prune does not touch protected items (system pages), items without a slug, and items with managedBy.

Permissions: nucleo/site-import: manage_options, scope nucleo:admin. nucleo/media-upload: upload_files, scope nucleo:write. nucleo/content-upsert: edit_posts, scope nucleo:write. nucleo/terms-set: manage_terms of the taxonomy, scope nucleo:write.

Edition: Free

Known limits: the command exits with code 1 if there is at least one error. It also exits with 1 if site-import rejects the request (ok: false), for example rate_limited after the retries. A failed upload stops the push after saving in the manifest the entries already uploaded. For each file in conflict it prints the suggestion nucleo pull --only <file> or nucleo push --force <file>; for a file in content/ or terms/ the suggestion is nucleo pull without --only, which rejects them. Consents on content/ and terms/ are ignored with a warning. Images are looked up only in media/, not in subfolders, with extensions .jpg, .jpeg, .png, .webp, .gif, .avif.

Recommended flow for a conflict

What it does: summarizes the messages that the CLI and the import give for a file in conflict.

How to use it:

• To keep the site version: nucleo pull --only <file>, then reapply the local change. The previous local copy is in .nucleo-backup/. For a file in content/ or terms/, pull --only does not work: use nucleo pull, which rewrites the files with safety copies in .nucleo-backup/.
• To overwrite the site: nucleo push --force <file> (ability: force: ["<file>"]).

Parameters: none.

Permissions: as for nucleo pull and nucleo push.

Edition: Free

Known limits: none found.