Skip to main content
Pull reads the remote working definition. Push writes it. Neither operation changes the live version by itself.

Pull current state

The project link in .fluidrc identifies the definition. You can select a different definition explicitly:
Use --force only when you intend to overwrite local changes while switching definitions.

Reconcile concurrent changes

Before a remote write:
  1. Preserve your local changes in version control or a patch.
  2. Pull the current working definition.
  3. Reapply the intended local edits.
  4. Resolve cross-resource slug changes.
  5. Run local validation and review the diff.
Do not edit .portal-sync/ to suppress drift. It is tool-managed synchronization state.

Push the working definition

Use --yes only to skip the confirmation prompt:
--yes does not approve new widget network access. After package review, use interactive approval or the explicit --allow-network-widgets option.

What push does, in order

Push runs these steps in order and stops at the first one that fails. Debug a push in the same order.
  1. Check the project. Push needs portal/ and the synchronization state from a pull. Without them it stops and tells you to pull.
  2. Sync with the project’s Git repository. Push commits your whole project, except what .gitignore excludes, and pushes it to the portal’s Fluid-provided repository. Keep secrets in .env, which the generated .gitignore excludes. “Skipped git sync” followed by a reason is fine, and push carries on. If the Git push fails, push stops and publishes nothing. Your changes stay committed locally. When your branch and the repository have diverged, run git pull --rebase, resolve any conflicts, and run push again.
  3. Compare with the last pull or push. “Nothing to push.” means you have no local changes.
  4. Confirm. Push asks before it writes. --yes skips the question.
  5. Validate every file. Push checks every file against its schema, then checks that every navigation item points to an existing screen and every profile points to existing navigations and themes. Any error refuses the whole push before anything is written. The message names the file and the missing slug.
  6. Approve widget capabilities. A changed screen that places a widget which newly asks for a capability, such as network access, needs your approval. See Push without prompts.
  7. Write in phases. Screens and themes first, then navigations, then profiles. When a phase fails, push skips the later phases. Only the files that were written count as pushed, so fix the problem and run push again to send the rest.
No mapping found for screen slug "rewards" (or theme, navigation or profile) means push has no record of that resource on Fluid. It happens when you change or delete a file that was never pulled or created remotely. Pull again, then reapply your change.

Recover from a partial push

Push can partially succeed. If a phase fails, earlier successful changes can remain. A push that doesn’t finish every phase ends with “Push completed with issues:” and exits with a non-zero code. Read the command result. Inspect the remote state and the tool-managed synchronization state. Fix the reported local resource and rerun validation and push. Do not assume the operation rolled back.
Do not add --activate to the normal synchronization workflow. First make the working definition correct. Then create and activate a version as separate release steps.