Instance commands
zeon up, down, brief, run, wait, stop, reset-arms, answer, logs, py, snap, open, app, say and look: drive your cloud instance.
These commands act on the cloud instance bound to your account. The CLI finds it on its own from your token. They never prompt, and they all take --json (one JSON object on stdout, errors included). For how a coding agent uses them, see Working with a coding agent.
zeon brief, zeon py, zeon snap, zeon say, zeon look and zeon open (the viewer link) use the instance's REPL, which Zeon enables per account. The others work without it. For how these commands fit together, see The REPL.
zeon up
zeon up [--project ID] [--world W] [--timeout 300]Loads the project's last pushed version on your instance, then a world, then prints the viewer link. --project defaults to the project of the current folder; --world to active_world in project.json. If the project names a setup your organization may use and the instance runs another, the instance switches to it first, which can take minutes.
project: <project name> (<project id>)
setup: <setup name>
world: shaker_deck
viewer: <link>
project: names the project loaded (its id alone when the name is unknown; project_name in --json). setup: is the setup the instance runs. If project.json asks for another one, a warning: line on stderr says so (setup_warning in --json): moves are planned for the setup the instance runs.
If some of the world's objects could not be loaded (a type neither in the project's objects/ nor in the mesh database your organization can see), it warns world W loaded WITHOUT N object(s) and lists them; skills that use them fail. Needed once per session and after an instance restart; zeon push and zeon sync refresh a project that is already loaded.
zeon down
zeon downReleases your instance: released instance <id>, or nothing to release (no instance is bound to you). Safe to repeat. It also ends the browser sessions that your token's login links started, and the 3D viewer link stops working. While a run is still going on the instance, the release is refused and the instance stays yours: wait for the run (zeon wait ID) or stop it (zeon stop ID), then zeon down again.
After zeon down, a later instance command still works, but it takes an instance again. The first one that does prints, on stderr:
notice: you released your instance with `zeon down`; this command took one again (`zeon down` releases it when you are done)
zeon up takes the instance without this notice. zeon push and zeon sync do not take an instance just to refresh it.
zeon brief
zeon brief [--timeout 60]One call to get oriented: the project, the setup the instance runs (and a warning when it is not the project's), the world and its objects, each arm's state (what it holds, whether it is at its start position, its joints), the project's active workflow, the skills and workflows with their inputs, and recent runs.
zeon run
zeon run NAME [-i KEY=VALUE ...] [--world W] [--kind auto|skill|workflow] [--motion fast|full] [--speed 1|2|4|8]
[--detach] [--timeout 120]Starts a simulated run and waits for it. By default it runs Fast at 8x: every move is planned as it would be on the robot, then played back at the chosen speed.
| Option | Meaning |
|---|---|
NAME | A skill id, or a workflow id or display name. |
-i, --input KEY=VALUE | An input value; parsed as JSON when it parses, else text. Repeatable. Workflow inputs you leave out take their defaults. |
--world W | Load world W before the run. |
--kind | auto (default): a workflow if one matches NAME, else a skill. |
--motion fast|full | fast (default): planned, then played back at --speed. full: the robot's own control and safety loops, in real time. |
--speed 1|2|4|8 | Playback speed of a Fast run (default 8). Not with --motion full, which always runs at 1x. |
--detach | Print the run id and return at once. |
--timeout S | Stop waiting after S seconds (default 120); the run continues. |
It prints started workflow <name>: <id> (Fast, 8x) on stderr and run <id> completed at the end. Ctrl+C cancels the run. A workflow runs from the project's file as loaded on the instance.
Iterate with Fast runs. Before a workflow goes to the real robot, run it once with --motion full. A Full run is real time and usually outlasts the default wait, so start it with --detach and follow it with zeon wait ID:
zeon run "Plate Transfer" --motion full --detach
zeon wait <id> --timeout 600An object input takes the object's instance id, its display name, or an object type the loaded world has exactly one instance of: the run maps a name or a type to the instance id before it starts. A display name that several objects share is refused with their ids.
Checks before the run starts
zeon run checks the name and the inputs against what the instance has loaded. A refused run has not started; the error says so (nothing was started) and names what to fix:
| Refusal | Exit | error in --json |
|---|---|---|
No skill or workflow NAME on the instance. The error suggests the closest names (did you mean 'move_plate'?), or says that workflows/NAME.json in your folder is not valid JSON or not pushed yet. | 2 | not_found |
An -i key that is not an input of the skill or workflow (with the closest input name and the full input list). | 2 | unknown_input |
A skill run that leaves out a skill parameter without a default. (A workflow input without a defaultValue may be left out: the skill's own default applies, and the instance refuses the start when a skill parameter ends up with no value.) | 2 | missing_input |
A value of the wrong type for an input declared int, float or bool (-i rounds=two for an int; a string that converts, such as "2", passes, as on the instance). | 2 | bad_input |
| A workflow node names a skill the project on the instance does not have. | 1 | skill_not_found |
You run it from a project folder and the instance has another project (or none) loaded. Run zeon up first. | 2 | project_not_active |
Outside a project folder, zeon run runs in the project the instance has loaded and prints a notice: line naming it.
The instance checks again when the run starts (the app's Run too), and refuses a start with a missing required input, a value of the wrong type, a node naming a missing skill, or (for a skill run) an object the world does not have (exit 1, run_not_started). Its message names the node, the skill, the input and its type.
When a run fails
A failed run's error ends with where it failed: the skill, the workflow node, and the line of the skill's own code that raised, for example [skill move_plate, node transfer, robotic_code.py:57]. The next: line depends on the error:
| The run | next: says | error in --json |
|---|---|---|
| was stopped | start it again with zeon run (a stopped run does not resume) | run_cancelled |
| failed because an arm was left touching something by an earlier run | zeon reset-arms, then run again | arm_in_contact |
| failed because a workflow node names a skill the project lacks | fix the node's skill_id or sync the skill | skill_not_found |
| failed on a missing input or one of the wrong type | zeon brief lists each input with its type; run again with -i name=value | bad_input |
| failed in the skill's code | zeon logs ID shows where it stopped; fix the skill, zeon sync, run again | run_failed |
zeon wait and zeon logs -f give the same next: line for a run that ended this way.
zeon wait
zeon wait ID [--timeout 120]Waits for a run. Exit 0 when it completed, 1 when it failed or was cancelled, 5 when it is still running at the timeout (a run paused for a person reports that it is paused). Ctrl+C stops waiting; the run continues.
When a run is waiting for an answer to an ask_user_slack prompt, a timed-out zeon run or zeon wait says so (an ask_user_slack prompt waits for an answer, in Slack, the app or zeon answer; "waiting_on_prompt": true and the prompt in --json). Answer it with zeon answer, then zeon wait ID again.
zeon stop
zeon stop ID [--timeout 60]Stops run ID, as Stop in the app does, and waits for it to end: run <id> cancelled. A workflow ends after its current step. A stop is final: the run does not resume; start a new one with zeon run. A run that had already ended is left as it is: run <id> had already ended (<status>).
Exit 0 once the run has ended, 5 when it is still ending at the timeout (zeon wait ID follows it), 2 for an unknown run id, 1 when the instance refused the stop.
zeon reset-arms
zeon reset-armsPuts both simulated arms back at their start position: the grippers open, an object an arm holds is let go where it is, and nothing is planned, so it works wherever the arms ended up. The world's objects stay where they are; to put them back, reload the world (zeon run NAME --world W or zeon up --world W). It does the same as Reset in the Skills Editor and the Workflow Editor.
$ zeon reset-arms
Both arms are back at their start position; 1 held object(s) released where they were
Use it after a run that stopped half-way left an arm holding or touching something (a later run fails with the arm starts with ... from '<object>').
It is refused while a run is in progress (exit 1; next: names zeon stop ID), and off the cloud simulation (exit 2). --json gives message, released (the number of objects let go) and joints (each arm's joint values after the reset).
zeon answer
zeon answer ID [CHOICE]Answers the open ask_user_slack prompt of run ID, as its buttons in Slack or the app would. Without CHOICE it prints the question and its options and exits with 2. CHOICE is an option's label or value; case is ignored when only one option matches. The first answer wins: an answer given in Slack or the app first is refused with exit 1.
$ zeon answer <id>
Did the plate seat correctly?
Yes, continue (value: ok)
No, seat it again (value: retry)
$ zeon answer <id> "Yes, continue"
answered <id>: Yes, continue
zeon logs
zeon logs ID [-f] [--timeout 120] [--out FILE] [--max-chars 16000]Prints the run log, one line per entry: step starts and ends, what the skills printed with print_log (under their step), notes, and the final COMPLETED or FAILED: <error>, for a workflow run and for a run of one skill. -f follows the log until the run ends and exits with the run's outcome. An unknown run id exits with 2.
zeon py
zeon py 'CODE' [--timeout 120] [--out FILE] [--max-chars 16000]
zeon py -f FILERuns Python in the instance's REPL against the simulation and prints the output: what the code printed, then the value of its last expression. -f - reads the code from stdin. On timeout or Ctrl+C the entry is interrupted. Entries share one Python session: names defined in one entry stay for the next. Do not rely on them after an instance restart or zeon down. Entries run one at a time. The namespace has the skill API, sim, skills, run_workflow, snapshot, say, look and brief; see What you can use in the REPL. A guard checks each entry; a refused entry exits with 4 and prints what was refused and a hint:
refused by the REPL guard (static): os.environ is not available
hint: ...
next: change the code to use the skill API and submit again (the refusal is logged)
zeon snap
zeon snap [PATH] [--view sim] [--timeout 60]Saves a PNG picture of the simulation viewer to PATH: saved <path> (<n> bytes). Without PATH, inside a project folder it saves to .zeon/snaps/snap-<id>.png (never committed or synced, so a picture does not show up as a change); elsewhere to snap-<id>.png in the current folder. The instance renders it; no browser needs to be open.
zeon open
zeon open [--viewer sim] [--gizmos] [--browser]Prints the 3D viewer link: the view to share with the people watching. It needs no sign-in; the link carries its own token and stops working after zeon down. The viewer's gizmos (the object and arm handles, the grid and the workspace box) are hidden first so the link shows just the cell; --gizmos shows them instead. This applies to every view of the simulation, including the app; gizmos(True) in the REPL or the gizmo button in the app brings them back. --browser also opens the link.
zeon open --workflow W and zeon open --canvas W still work: they print the same link as zeon app W --run and zeon app W, with a notice to use zeon app. Unlike zeon app W, zeon open --canvas W is refused when the workflow has no canvas.
zeon app
zeon app [W] [--run] [--world W] [--project ID] [--no-login-link] [--browser] [--json]New in CLI 1.5.5. Prints your personal link into the web app, signed in:
| Command | The link opens |
|---|---|
zeon app | the project's page |
zeon app W | workflow W's run screen on its Inputs tab, with the canvas rendered beside the simulation; when W has no canvas, its run screen and a notice (zeon new canvas W makes one) |
zeon app W --run | workflow W's run screen (graph and inputs) |
W is a workflow id or display name. --world selects a world (default: the one loaded) and --run / --world need a W; --project names another project id (default: the folder's); --browser also opens the link. The link is refused unless the project is the one the instance has loaded (zeon up first), because opening another project would switch the instance. It opens the pushed version, so zeon sync first, and it never clears the loaded world.
The link is a login link, https://zeonsystems.app/auth/link?code=...&next=<app path>: it signs the browser that opens it in to your account and goes on to the page. It is personal; do not share it (share zeon open instead). The code works once, within 5 minutes; an expired or used link falls back to the sign-in page, which then returns to the page. The browser session lasts 12 hours and ends earlier on sign-out in the browser, zeon down, zeon logout, or the CLI token being revoked. &ui=operator added to the end of the link opens the app in operator mode. --no-login-link prints the plain app link. The CLI also prints the plain link when ZEON_APP_URL is set, and, with a notice: line, when the server does not offer login links. With --json, url is the link to open, app_url the plain app link and login_link whether url is a login link. See Login links from the CLI.
zeon say
zeon say "TEXT" [--timeout 30]Posts TEXT to the viewer's Agent panel: said: TEXT.
zeon look
zeon look TARGET [--seconds 6] [--timeout 30]Points the viewer camera at TARGET and highlights it for --seconds. TARGET is an object id, <holder>.<anchor>, or a preset name from viewer.yaml. A target it cannot find exits with 2 and says why, naming the targets it could mean.
Output limits
zeon py and zeon logs show at most --max-chars characters inline (default 16000; 0 for no limit), keeping the start and the end. --out FILE writes the full text; without it, a capped output names a temporary file that holds all of it.
Exit codes
| Code | Meaning |
|---|---|
| 0 | ok |
| 1 | the entry or run failed |
| 2 | usage: bad arguments, unknown id or name, run inputs refused before the start, another project loaded, project not pushed yet |
| 3 | not signed in, token rejected, or not enabled for the account |
| 4 | refused by the REPL guard |
| 5 | timed out, or stopped waiting |
| 6 | instance unavailable: starting, restarting, no free instance |
Every error ends with a next: line (or a next field in JSON) that says what to do.
Updated about 19 hours ago