CLI cheat sheet
Every zeon command in one table, plus the situations you will actually hit.
Fast lookup. Every command supports --help, e.g. zeon sync --help.
If you remember one command, remember
zeon sync. It pulls, merges, and pushes in one step, and it is safe to run at any time. Seezeon sync.
Install and update
uv tool install zeon # install
uv tool install zeon --reinstall # update to the latest release
uv tool list # check which version you have
zeon --help # list every commandCheck your version after updating.
zeon --helplists commands but does not print a version.uv tool listdoes. An out-of-date install is a common source of "that flag doesn't exist for me."
Every command
Run the working-tree commands from inside a project folder. The CLI finds the project by looking for a .zeon/ directory in the current folder or above it.
Sign in
| Command | What it does |
|---|---|
zeon auth login --global | Browser sign-in, stored per machine. |
zeon auth login --token <zat_…> --global | Store a token you already have. |
zeon auth status | Show the active credentials and ping the server. |
zeon auth logout [--global] | Remove the stored token. |
login also takes --name <label> (how the token is labelled in the web UI) and --expires-in-days <n> (default 90, max 365). Full detail: zeon auth.
Start or get a project
| Command | What it does |
|---|---|
zeon new project <name> [<target-dir>] | Create a cloud project and a local working tree. Takes --description. |
zeon clone <name-or-id> [<target-dir>] | Download an existing cloud project. |
zeon init [-m "<msg>"] | Turn the current folder into a new cloud project. Needs skills/, workflows/, and worlds/ to exist. |
Everyday
| Command | What it does |
|---|---|
zeon sync [-m "<msg>"] | Pull, merge, and push in one step. |
zeon status [--json] | What changed versus your last commit. |
zeon diff [<paths>…] | Line-by-line review of those changes. |
zeon commit -m "<msg>" [<paths>…] | Local snapshot. Does not touch the cloud. |
zeon push | Send local commits to the cloud. |
zeon pull [--force] | Fetch the cloud and merge it into your tree. |
zeon log [-n <N>] [--from <sha>] [--json] | Recent commits. |
-m is required on zeon commit. Detail on each: working-tree commands.
Create content
| Command | What it does |
|---|---|
zeon new skill <name> | Scaffold skills/<name>/. |
zeon new workflow <name> | Scaffold a workflow. |
zeon new world <name> | Scaffold worlds/<name>/. |
zeon new canvas <workflow> | Attach a React canvas to a workflow that already exists. |
zeon new object <name> | Write objects/<name>/ from the mesh database. |
These write files locally only. Run zeon sync afterwards. Detail: zeon new.
Projects
| Command | What it does |
|---|---|
zeon project list [--archived] [--json] | All your projects. |
zeon project show <name-or-id> [--json] | Metadata for one project. |
zeon project rename <name-or-id> <new-name> | Rename. |
zeon project archive <name-or-id> | Soft-archive. |
Conflicts and recovery
| Command | What it does |
|---|---|
zeon sync --continue | Finish a sync after you resolved the conflicts. |
zeon sync --abort | Cancel an in-progress sync, keep your local work. |
zeon checkout <sha-or-ref> [--force] | Load a past commit into the working tree. |
zeon reset <sha> [--hard] | Move HEAD to <sha>; --hard also rewrites the working tree. |
Mesh database
| Command | What it does |
|---|---|
zeon mesh-database list [--tag <t>] | Browse the catalog. |
zeon mesh-database show <name> | Details for one item. |
zeon mesh-database download <name> <dest> [--force] | Mirror an item to a local folder. |
zeon mesh-database upload <name> <src> | Admin only. Takes --visibility, --tag (repeatable), --source. |
zeon mesh-database delete <name> [--yes] | Admin only. |
To bring a catalog object into a project, prefer zeon new object <name>. Detail: zeon mesh-database.
Situations you will hit
Day one, from nothing
uv tool install zeon
zeon auth login --global
zeon new project my-project
cd my-project
# …edit files…
zeon sync -m "First pass"The daily loop
zeon status # what did I change
zeon diff # review it
zeon sync -m "Adjust waypoints" # merge cloud + push, one stepYou edited in the Web IDE, then edited locally
Sync. It merges both sides when the edits do not overlap.
zeon sync -m "Local tweaks"zeon push refused because the cloud moved
zeon push refused because the cloud movedzeon push
# → the cloud has changed since your last sync. Run `zeon sync` to
# merge your work with the cloud and push.
zeon syncA real conflict, same lines changed both places
zeon sync
# → CONFLICT worlds/bench_layout/world_state.json
# merge needs your input. Edit the file(s) above to keep what you want,
# then run `zeon sync --continue`.
# …open the file, keep what you want, delete the <<<<<<< ======= >>>>>>> lines…
zeon sync --continueChanged your mind mid-conflict:
zeon sync --abort # keeps your local workYou want a teammate's project on your laptop
zeon auth login --global
zeon clone my-project
cd my-project
zeon syncYou already have a folder and want it in the cloud
cd ./my-project # must contain skills/ workflows/ worlds/
zeon init -m "Import existing project"The folder name becomes the project name. It fails if .zeon/ already exists, or if a project with that name is already in your account.
You made a mess and want the cloud version back
zeon log # find the commit you want
zeon reset --hard <sha> # discards uncommitted work, matches that commit
zeon reset --harddiscards uncommitted work. There is no undo. Runzeon statusfirst.
Not yet available
| Command | Status |
|---|---|
zeon verify | Registered but not implemented. It prints a message and exits with status 1. Server-side IK and collision checking of a workflow is planned, not shipped. |
Where to go next
Updated 3 days ago