Working-tree commands

zeon clone, status, diff, commit, push, pull, log, checkout and reset.

Run these inside a project folder (or a folder below it), except zeon clone. Errors print a short message and exit with code 1.

zeon clone

zeon clone PROJECT [TARGET_DIR] [--agent-guide | --no-agent-guide]

Creates a working tree from the cloud project's latest commit. PROJECT is the project id or name. TARGET_DIR defaults to ./<project name>/ and must be empty or not exist. Writes AGENTS.md and CLAUDE.md when the project has none (default --agent-guide).

cloned my-project into /path/to/my-project
  head: <sha>

zeon status

zeon status [--json]

Shows head and remote head, then files Added, Modified, Deleted and Unmerged (with conflict markers) compared with HEAD. It also lists run state that is Leaving the project and files Left out (over the 64 MB sync limit) (see What gets synced), and says when a merge is in progress. A clean tree prints working tree clean.

zeon diff

zeon diff [PATH...]

Prints a unified diff of each changed file against HEAD. Paths are relative to the current directory; a folder selects everything under it.

zeon commit

zeon commit -m MESSAGE [PATH...]

Records a local commit. Without paths it takes the whole working tree; with paths it takes those files or folders and keeps everything else as it was in HEAD. Prints created commit <sha> — <message>. Refuses when nothing changed (nothing to commit (working tree matches HEAD)).

zeon push

zeon push [--no-refresh] [--world W]

Sends your local commits to the cloud: pushed HEAD → <sha>. Refused when the cloud moved since your last sync (run zeon sync) or while a merge is in progress. When your instance has the project loaded, it is refreshed afterwards (see How sync works).

zeon pull

zeon pull [--force]

Merges the cloud's latest commit into your working tree. Refuses while you have uncommitted changes; --force merges into them anyway. Results:

OutputMeaning
already up to dateNothing new in the cloud.
fast-forwarded to <sha>You had nothing new; you now have the cloud's commit.
merged cloud changes from <sha> — run zeon pushBoth sides had changes; a merge commit was recorded locally.
up to date with the cloud — your local commits are ahead; run zeon pushNothing to merge; push your commits.
CONFLICT <path>Edit the file, then zeon commit -m "merge" and zeon push, or zeon sync --continue.

zeon log

zeon log [-n 20] [--from SHA] [--json]

Shows recent commits from HEAD (or --from) with their time, author email and message.

zeon checkout

zeon checkout SHA_OR_REF [--force]

Writes a past commit (or main) into the working tree and moves HEAD to it. Refuses when you have uncommitted changes; --force discards them.

zeon reset

zeon reset SHA [--hard]

Moves HEAD to SHA and abandons a merge in progress. Your files stay as they are unless you pass --hard, which also writes that commit into the working tree.

Neither checkout nor reset --hard deletes run folders, data/, .runtime/, plan caches or files over the size limit.


Did this page help you?