zeon auth

zeon auth manages your local API credentials. Three subcommands:

zeon auth login signs in (browser PKCE flow or paste-token) and stores the resulting token.
zeon auth status (or bare zeon auth) shows the active credentials and pings the server.
zeon auth logout removes the local token.

`zeon auth login`

Default flow opens your browser to the Zeon sign-in page, completes OAuth, mints a long-lived API token, and writes it to your .env.

zeon auth login                              # browser flow, writes to ./.env
zeon auth login --global                     # writes to ~/.zeon/.env instead
zeon auth login --token zat_aBc123…          # skip the browser; paste an existing token
zeon auth login --name "cli-laptop"          # set the token's display name
zeon auth login --expires-in-days 30         # set token TTL (1–365, default 90)

Flags

Flag	Default	Description
`--token <zat_…>`	(none)	Skip the browser flow; store the supplied token directly. Useful for scripts or for tokens you minted in the web UI.
`--name <string>`	`cli-<hostname>-<YYYYMMDD-HHMMSS>`	Display name for the token, shown in the API tokens page. The timestamp suffix is deliberate. It keeps repeated logins from the same machine distinguishable in the token list.
`--expires-in-days <N>`	`90`	Token TTL in days. Min 1, max 365.
`--global`	off	Write to `~/.zeon/.env` (per-machine). Default writes to `./.env` (per-directory).

What gets written

zeon auth login writes one line to the target .env file:

ZEON_API_TOKEN=zat_aBc123…

It also chmod 600s the file so it's only readable by you.

`zeon auth status` (or `zeon auth`)

Shows the resolved settings, where each one came from, and pings /sync/me to verify the token works.

zeon auth                  # equivalent to `zeon auth status`
zeon auth status

You'll see a table like:

setting          value                                       source
sync_url         https://zeonsystems.app/sync                default
identity_url     https://zeonsystems.app/api/account         default
cognito_domain   auth.zeonsystems.app                        default
cli_client_id    …                                           default
api_token        zat_…123                                    ./.env

✓ authenticated
  user_id: …
  email:   [email protected]
  org_id:  your-org

The source column tells you which .env (or shell env var) provided each value. Useful when you're chasing down which token is actually in effect.

If the token is missing or expired, zeon auth exits with code 1, which is handy for use in shell scripts (if ! zeon auth; then ...; fi).

`zeon auth logout`

Removes ZEON_API_TOKEN from the target .env. Other env vars in the file are left alone.

zeon auth logout            # removes from ./.env
zeon auth logout --global   # removes from ~/.zeon/.env

This only removes the local copy. The server-side token is still valid until its expiry. To invalidate it immediately, revoke it from the API tokens page in the web UI.

Environment variables

zeon auth honors these env vars, in order of precedence (highest first):

Real shell env (e.g., export ZEON_API_TOKEN=…).
./.env (auto-discovered by walking up from cwd).
~/.zeon/.env.
Built-in defaults.

Variable	Purpose
`ZEON_API_TOKEN`	Your API token. Required for every sync call.
`ZEON_SYNC_URL`	Sync service URL. Defaults to `https://zeonsystems.app/sync`.
`ZEON_IDENTITY_URL`	Identity service URL. Defaults to `https://zeonsystems.app/api/account`.
`ZEON_COGNITO_DOMAIN`	OAuth host. Defaults to `auth.zeonsystems.app`.

You typically only set ZEON_API_TOKEN and let the rest default.

Per-directory tokens

Because ./.env takes precedence over ~/.zeon/.env, a project directory can have its own token that overrides the machine-wide one. Useful for:

A sandbox project pointing at a different environment.
Running scripts as a different user without touching the global token.
CI/CD setups where the working directory has its own token.

To set this up:

cd ~/my-special-project
zeon auth login                    # without --global; writes to this project's .env

Where to go next

API tokens

Manage tokens in the web UI: list, revoke, mint new ones.

zeon working-tree commands

What you actually do after you're signed in.

zeon auth login