Install the CLI

The zeon CLI is how you move work between your computer, the Zeon cloud, and the lab machine attached to the robot. Install it once per machine, sign in once per machine, and you are ready to start a project.

The current published version is 1.2.2. It needs Python 3.9 or newer.

Install

There are two routes. Pick one.

With uv (recommended)

uv tool install --force zeon

This is the route to prefer. uv tool install puts the CLI in its own isolated environment and puts the zeon executable on your PATH, so nothing you install later in a project virtualenv can break it, and you do not have to remember to activate anything before running zeon. The --force flag makes the command safe to re-run. Without it an existing installation is left as it is, so --force is what picks up a newer release.

With pip

pip install --upgrade zeon

Use this if you do not have uv. It works, but the CLI then lives in whichever Python environment was active when you ran it. If you later switch virtualenvs, zeon may not be on your PATH. --upgrade also doubles as the update command.

Check that it worked

zeon --help

You should get the top-level help, listing the command groups: init, new, auth, project, mesh-database, and the working-tree commands (clone, status, diff, commit, push, pull, sync, log, checkout, reset).

If your shell says zeon: command not found, the executable is not on your PATH. With uv, run uv tool update-shell and open a new terminal. With pip, check that you are in the same environment you installed into.

Sign in

zeon auth login --global

This opens your browser at the hosted sign-in page for auth.zeonsystems.app. Sign in there with the account your organization invited you with. When the page redirects back, the CLI has what it needs and you can close the tab.

What happens under the hood:

1. The CLI starts a one-shot HTTP listener on localhost:8765 to catch the redirect.
2. It opens your browser at the hosted sign-in page. If the browser does not open on its own, the CLI prints the URL so you can paste it in.
3. After you sign in, it exchanges the returned code for a long-lived API token.
4. It writes that token to a .env file as ZEON_API_TOKEN, with file permissions set to owner-only.
5. It calls the server to confirm the token works and prints the email it signed you in as.

The CLI waits up to five minutes for you to finish in the browser. If you are on a machine with no browser, use the paste route described below instead.

What --global does

Without --global, the token is written to .env in the directory you ran the command from. The CLI reads that file from there and from any directory below it, so it scopes the credential to one project rather than the whole machine.

With --global, the token is written to ~/.zeon/.env instead, which every project on the machine picks up. On your own laptop this is what you want, so you sign in once rather than once per project.

Both files can exist. A project-local .env wins over ~/.zeon/.env, and a real shell environment variable wins over both. That ordering is deliberate, so a CI working directory or a sandbox project can override your machine-wide credentials.

Other login options

Tokens minted this way show up on the API tokens page, where you can revoke them.

Confirm you are signed in

zeon auth status

This prints a table of the settings the CLI resolved, with the source of each one, so you can see exactly which file a value came from:

• sync_url, identity_url, cognito_domain, cli_client_id
• api_token, masked to its first four and last three characters

The source column reads env, a path to a .env, ~/.zeon/.env, ~/.zeon/config.toml, or default. If you signed in with --global, expect the token's source to be ~/.zeon/.env.

It then contacts the server with that token and prints ✓ authenticated along with your user_id, email, and org_id. If the token is missing or rejected, the command fails with a non-zero exit code and tells you which. Running zeon auth on its own does the same thing.

Install the Claude Code skill (optional)

If you build with Claude Code, install the Zeon project skill. It teaches Claude Code the Zeon project layout, the file formats, and the runtime API, so what it writes validates instead of only looking right. Skip this if you edit files by hand.

The skill ships as a Claude Code plugin from a marketplace named zeon. Install it from your terminal with the claude CLI: add the marketplace, then install the plugin.

claude plugin marketplace add zeonsystems/zeon-project-skill
claude plugin install zeon-project-skill@zeon

If you were handed a local copy of the plugin instead of a repository link, point the first command at that folder:

claude plugin marketplace add ~/path/to/zeon-project-skill

Restart Claude Code after installing, so the new session loads the plugin. This means restarting Claude Code itself (end your session and run claude again), not the terminal. Your shell and the zeon CLI are unaffected. The zeon-projects skill then becomes available, and you can describe what you want built ("add a skill that ejects the pipette tip", "why does my workflow fail validation?") in any project folder.

Updating the skill

If you already have the skill and want the latest version:

claude plugin update zeon-project-skill@zeon

Include the @zeon marketplace suffix. As with installing, the update applies on the next Claude Code session, so restart Claude Code (not the terminal) to pick it up.

If an update ever leaves the skill in a bad state, remove and reinstall it instead:

claude plugin uninstall zeon-project-skill@zeon
claude plugin install zeon-project-skill@zeon

You are set up

Two things to read next, in this order.

For the full flag-by-flag reference on the auth commands, see zeon auth.