Synchronize local changes

These steps are for developers who work on a workspace with the hmi CLI. They send the changes in a pulled workspace to the cloud and bring cloud changes into it. How pull, push, and conflicts work is in About local sync. Every command and error code is in the CLI reference.

Review what push will send

1. Run pnpm hmi status to list local changes, conflicts, and the local and server revisions.
2. Run pnpm hmi check and fix every error it prints.
3. To see the exact plan, run pnpm hmi push --dry-run. It prints the setup operations, changed paths, and file counts as JSON and sends nothing, also while conflicts are unresolved.

Push your changes

1. Run pnpm hmi push. It builds the dashboards, runs hmi check, uploads the file contents the server lacks, and sends the changes. Nothing to push. means there was nothing to send.

2. If push fails or refuses, find the message in this table and follow its row, then push again:

   Message	Action
   push_conflict, or Refusing push: N unresolved conflict	Follow Resolve sync conflicts
   push failed: hmi check failed	Fix the errors printed after it
   Changed files under src/dashboards/<id> refused	Run pnpm hmi pull first. If the dashboard was deleted in the cloud, delete its folder
   push_admin_required	Put the workspace name and branding files back as they are on the server, or ask an admin or owner to push them
   push_validation_failed, other codes	Read details in the JSON after the code and fix that item; codes are in Push errors
   No answer, or unfinished push in hmi status	Follow Retry an interrupted push
   push_id_reused	Follow Retry an interrupted push

Retry an interrupted push

If push gets no answer, for example because the network dropped, the server may or may not have applied it. hmi status then shows unfinished push: <id>.

1. Run pnpm hmi push again. It sends the push under the same ID, and the server returns the result of the first attempt instead of applying the changes twice. The server remembers push IDs for 30 days.
2. If push fails with push_id_reused, the ID cannot be used for this push: an earlier attempt was applied but its answer was lost and your local changes have changed since, or someone else’s push uses the ID, for example from a copied setup.db. The CLI drops the ID. Run pnpm hmi pull, then pnpm hmi push again.

Get changes from the cloud

1. Run pnpm hmi pull. Your local changes stay. Server changes to everything you did not change are applied.
2. If pull reports conflicts, follow Resolve sync conflicts.
3. If the CLI refuses setup.db as newer than itself, update @overvis/hmi-cli.
4. If the CLI says setup.db is too old to upgrade, run pnpm hmi export --local > <file> to keep a raw dump, then pnpm hmi pull --rebuild. Add --discard-local if it refuses because of local changes.

Run pnpm hmi pull before you push when you know the workspace changed in the cloud, for example after logo or favicon edits in workspace settings.

Back up and restore local changes

Pull, resolve, and push handle concurrent edits. To start from a clean cloud copy and re-apply your work as a reviewed merge instead:

1. Make a local-only archive. It needs no clean checkout and contacts no server:

   pnpm hmi download --no-readings --no-const-values ../mine.sqlite

   The archive holds the complete local setup and synced files, including new and edited files. It may contain endpoint PIN codes: store it as a secret.

2. Replace the local copy with the cloud copy:

   pnpm hmi pull --discard-local

3. Merge the archive back and push it:

   pnpm hmi upload ../mine.sqlite

   upload compares the archive with the freshly pulled checkout, asks before each conflict, applies the selected changes, and pushes them. Use --force only after reviewing the archive and the destination.

To keep only a JSON copy of local edits, pnpm hmi export > <file> writes the unpushed changes and pnpm hmi import <file> applies them again; see export / import.