zeon working-tree commands

These are the everyday commands you'll run after creating or cloning a project. Each one operates on the working tree you're inside. The CLI walks up from cwd looking for a .zeon/ directory, so you don't need a --project flag.

⭐
Most of the time you want zeon sync. It does pull, merge, and push in one step, and it can't be rejected for being out of date. The commands on this page are the finer-grained pieces underneath it.

Command	What it does
`zeon sync`	Pull, merge, and push in one step ⭐
`zeon clone`	Bootstrap a local working tree from a cloud project
`zeon status`	Show files changed since the last commit
`zeon diff`	Textual diff of changes
`zeon commit`	Snapshot the working tree as a new local commit
`zeon push`	Send local commits to the cloud
`zeon pull`	Fetch cloud commits; merge if needed
`zeon log`	Show commit history
`zeon checkout`	Materialize a past commit into the working tree
`zeon reset`	Move the local tip to a past commit

`zeon clone`

Bootstrap a working tree from a cloud project.

zeon clone my-project                  # creates ./my-project/
zeon clone my-project ~/elsewhere      # creates ~/elsewhere/
zeon clone ab12cd34                    # by project id

If the target directory already exists, it must be empty. After clone, the working tree has every file from the project's main branch tip, plus a hidden .zeon/ directory with sync metadata.

`zeon status`

Show what's changed since the last commit.

zeon status
zeon status --json

Output groups files by state:

Modified:
  workflows/my_workflow.json
  skills/dispense/robotic_code.py

Added:
  worlds/new_layout/world_state.json

Deleted:
  skills/old_skill/metadata.yaml
  skills/old_skill/robotic_code.py

If everything is up to date with HEAD, you'll see "Working tree clean".

`zeon diff`

Textual diff per file, suitable for review before committing.

zeon diff                                    # working tree vs HEAD
zeon diff workflows/my_workflow.json         # a single file
zeon diff workflows/                         # everything under a directory

zeon diff only ever compares your working tree to your last commit. It takes paths, not commit ids, so there is no way to diff two commits against each other.

For .json and .py files you get a unified-diff style output. For files the CLI can't text-diff (binary), it notes "binary file changed".

`zeon commit`

Snapshot the current working-tree state into a new local commit.

zeon commit -m "Adjust dispense volume"
zeon commit -m "Add new world"  worlds/new_layout/   # commit only specific paths

If no paths are given, every change (modified, added, deleted) is included. If paths are given, only changes under those paths are committed; other modifications stay uncommitted.

Commit only writes locally; nothing reaches the cloud until you zeon push.

`zeon push`

Send your local commits to the cloud.

zeon push

Sends every commit since the last successful push. If the cloud has moved on (someone else pushed in the meantime), zeon push fails with a "diverged from cloud" message. Run zeon sync, which reconciles and pushes in one step. (zeon pull then zeon push works too, and is the same thing done by hand.)

`zeon pull`

Fetch new commits from the cloud and merge them into your local tree.

zeon pull
zeon pull --force                  # pull even with uncommitted changes

zeon pull refuses to run when your working tree has uncommitted changes, matching git's behaviour. It names the dirty files and tells you to commit, revert, or force.

⚠️
--force does not discard anything. It pulls despite the dirty tree, 3-way merging cloud changes into your uncommitted state. That's riskier than it sounds: your in-flight edits and the cloud's edits get interleaved in place. To actually discard local work and match the cloud, use zeon reset --hard instead.

One of four things happens:

No new commits. Prints already up to date.
Cloud is ahead, you have no local commits. Fast-forwards your tree to match.
You're ahead, the cloud had nothing new. It reports that you are up to date with the cloud, that your local commits are ahead, and that you should run zeon push.
Both sides have new commits. Pull merges them. Clean merges are recorded for you as a merge cloud changes commit; real conflicts get 3-way markers written into the files, and pull exits with status 1. You edit, then zeon commit -m "merge" and zeon push (or zeon sync --continue).

See Resolving "Diverged from cloud" for the conflict-marker flow.

--force does not discard anything. See the warning above: it pulls despite a dirty tree and merges the cloud's changes into your uncommitted work. To actually discard local changes and match the cloud, use zeon reset --hard.

📘
zeon pull refuses to run on a dirty working tree unless you pass --force. zeon sync has no such restriction: it commits your uncommitted work first, so it's the safer choice when you have edits in flight.

`zeon log`

Show commit history, newest first.

zeon log                       # last 20 commits
zeon log -n 50                 # last 50
zeon log --from <commit-id>    # everything reachable from a specific commit
zeon log --json                # machine-readable

Each entry shows the commit id (short), the message, the author, and the timestamp.

`zeon checkout`

Materialize a past commit or a ref into the working tree.

zeon checkout <commit-id>            # see what the project looked like at this commit
zeon checkout main                   # back to the current tip
zeon checkout <commit-id> --force    # discard local changes when switching

By default, refuses if the working tree has uncommitted changes (you'd lose them). Use --force to discard.

zeon checkout is non-destructive to the cloud. Nothing in the cloud changes; you're only moving what's on disk.

`zeon reset`

Move the local tip ref to a past commit. Use carefully, because this can lose commits if you push afterwards.

zeon reset <commit-id>             # move HEAD; working tree untouched
zeon reset --hard <commit-id>      # move HEAD and reset the working tree

zeon reset --hard <commit-id> is the "I want to undo everything since this commit" operation. Followed by zeon push, it rewrites history in the cloud, usable but dangerous (you'll lose any commits another machine had pushed between then and now).

If you're not sure, prefer zeon checkout (which is non-destructive) and only reset once you're certain.

Where to go next

Resolving Diverged from cloud

Merging when both sides moved.

Commit, push, pull with the CLI

The narrative version of all this.