CLI reference

The genlabz CLI is the primary interface for interacting with the GenLabZ platform from your terminal. It handles authentication, and will grow to cover project management and event coordination as those services come online.

Installation

The CLI is distributed as a Python package in the monorepo. Install it with uv:

cd packages/genlabz-cli
uv sync
source .venv/bin/activate

After activation, genlabz is available on your PATH.

Synopsis

genlabz [--json] [--verbose] <command> [<subcommand>] [options]

Global flags

These flags apply to every command and must be placed before the command name.

Flag	Short	Description
`--json`	—	Output results as machine-readable JSON instead of formatted text
`--verbose`	`-v`	Print diagnostic information to stderr — resolved config values and full tracebacks on error
`--help`	—	Show help for the current command or subcommand and exit

Configuration

The CLI uses baked-in defaults for production endpoints. Override them with environment variables for local development or testing.

Variable	Config key	Default
`GENLABZ_AUTH_URL`	`cognito_domain`	`auth.genlabz.com`
`GENLABZ_API_URL`	`api_url`	`api.genlabz.com`

Run with --verbose to print the resolved config to stderr before any command executes:

genlabz --verbose auth status

Commands

`auth`

Manage platform authentication. See Authentication for a full walkthrough.

genlabz auth login    # sign in via browser (PKCE flow)
genlabz auth status   # show current auth state and token expiry
genlabz auth logout   # revoke and clear stored tokens

Running genlabz auth with no subcommand prints the auth help and exits.

Exit codes

Code	Meaning
`0`	Success
`1`	User error — bad arguments, not logged in, validation failure
`2`	Unexpected error — unhandled exception, network failure
`130`	Interrupted — Ctrl+C / SIGINT

Scripts can rely on these codes for conditional logic:

genlabz auth status || genlabz auth login

JSON output

Pass --json to get machine-readable output from any command. This suppresses table rendering and colour codes:

genlabz --json auth status