zeon sync

zeon sync pulls the latest cloud changes, merges them with your local work, and pushes, in one step.

zeon sync                          # uses a default commit message
zeon sync -m "Tune gripper offsets"

Mental model

Run sync from inside a project folder. The CLI finds the project by looking for a .zeon/ directory in the current folder or above it, so there is no project flag to pass and the depth you run from does not matter.

Flags

How zeon sync works

1. Checks the cloud. If nothing moved on either side, it prints already up to date and stops.
2. Snapshots uncommitted work. If your working tree is dirty, sync commits it first so nothing can be lost.
3. Merges the cloud's files into your working tree, file by file.
4. Pushes the result and reports the new commit.

Because it always pulls before it pushes, sync removes the most common failure mode, a zeon push rejected because the cloud moved on. It stops only when the same file changed in both places and the two edits genuinely overlap.

How a file is merged

For each file, sync compares three versions: the common ancestor, yours, and the cloud's.

Outcomes of a clean sync

You do not need to tell these apart. They all mean it worked. They are listed because the commit count in zeon log differs between them.

Conflicts

When you and the cloud changed the same lines of the same text file, sync writes standard markers into that file, prints CONFLICT <path> for each one, and exits with status 1:

<<<<<<< HEAD
your version
=======
the cloud's version
>>>>>>> remote

HEAD is your side. remote is the cloud's side. Open the file, keep what you want, and delete all three marker lines. Then run zeon sync --continue.

During a conflict

--abort is lossless. Because sync committed your uncommitted edits before merging, aborting restores exactly what you had and drops the conflict markers.

If you start a fresh sync while one is in progress, it refuses and tells you to --continue or --abort first.

Binary files

A binary file, a mesh or an .npz for example, cannot be line-merged. When one changed in both places, sync keeps the cloud version in your tree, saves your version under .zeon/backups/<path>, and carries on rather than stopping. It prints a line naming the file and the backup location.

This is not a conflict you have to resolve. The sync completes. But if yours was the version you wanted, copy it back out of the backup and sync again.

Doing it step by step

sync is commit, pull, merge, and push collapsed into one command. The pieces still exist on their own, and there are jobs only they can do.

Reach for the explicit path when you want to build up several commits locally before sending anything, when you want to read zeon status and zeon diff and decide before anything reaches the cloud, or when you want to commit part of your working tree and leave the rest in progress:

zeon commit -m "Only the skill" skills/my_skill/
zeon commit -m "Two workflows" workflows/pick.json workflows/place.json
zeon push                                     # every local commit goes up together

With no paths, zeon commit includes every change: modified, added, and deleted alike. That is the main practical difference from sync, which always takes the whole tree. sync also works on a dirty tree, where pull refuses.

Worked stories

The daily loop

zeon status                      # see what you changed
zeon diff                        # review it
zeon sync -m "Adjust waypoints"  # merge cloud + push, one step

zeon status groups files as Added, Modified, Deleted, and Unmerged, and prints working tree clean when there is nothing outstanding.

"Someone else pushed while I was editing locally"

Sync. It merges both sides automatically when the edits do not overlap.

zeon sync -m "Local tweaks"

"The cloud moved and zeon push refused"

push stops rather than forcing anything, and tells you the cloud has changed since your last sync.

zeon push        # refused
zeon sync        # reconciles and pushes

push only sends. It never merges. sync is what reconciles the two sides. By hand, the same thing is zeon pull, resolve anything conflicting, then zeon push.

"Sync stopped with CONFLICT"

zeon sync
# → CONFLICT workflows/plate_prep.json

zeon status                # confirm which files are unmerged
# …edit workflows/plate_prep.json, remove the markers…
zeon sync --continue

"I resolved it wrong and want to start over"

zeon sync --abort
# → sync aborted

Then fix your files at leisure and run zeon sync again.

"A mesh came back different from what I had"

The sync finished and kept the cloud's copy. If you wanted yours, restore it from the backup and sync again:

cp .zeon/backups/worlds/bench_layout/mesh.npz worlds/bench_layout/mesh.npz
zeon sync -m "Restore local mesh"

"I am stuck mid-merge and want out entirely"

zeon sync --abort
zeon log                 # find a commit you trust
zeon reset --hard <sha>  # discards uncommitted work, matches that commit
zeon sync

"I want to see what the cloud has without pushing"

zeon pull

pull fetches and merges but never pushes. Its outcomes:

After resolving a conflict that came from pull rather than sync, finish it with zeon commit -m "merge" and zeon push.

pull refuses to run on a dirty working tree. It names the offending files and tells you to commit, revert, or pass --force.

Getting a project onto another machine

zeon clone my-project    # creates ./my-project/
cd my-project
zeon sync

If you already have a project folder on disk with no .zeon/ in it, register it instead. The folder must contain skills/, worlds/, and workflows/, and its name becomes the cloud project name:

cd ./my-project
zeon init -m "Import existing project"

On the lab machine

Sync before every run, so the workflow you are about to execute on hardware is the latest one:

zeon sync

Going the other way, after capturing a world next to the robot, the explicit path earns its keep. You can check zeon status and confirm you are sending the world snapshot and nothing else before it reaches everyone:

zeon status
zeon commit -m "Snapshot world after re-positioning plates"
zeon push