CLI

The optixlog binary is a Typer CLI that drives the complete developer workflow for the OptixLog Python SDK. Run it to authenticate with your API key, select which projects to generate types for, and emit a byte-deterministic typed Python module that turns schema mismatches into static type errors before your code runs.

Installation

Install the SDK package from PyPI. The optixlog binary is included:

pip install optixlog

Verify the installation:

optixlog --version

For development (from the python-sdk-spec/ source tree):

pip install -e ".[dev]"

Binary name

The entry point is optixlog. It is registered by the package at install time and is available anywhere on your PATH after pip install.

Global flags

No-args behavior

Running optixlog with no arguments or subcommand prints the top-level help and exits. This is intentional — the CLI is configured with no_args_is_help=True.

$ optixlog
Usage: optixlog [OPTIONS] COMMAND [ARGS]...

  OptixLog SDK — authenticate, select projects, and generate typed bindings.

Options:
  --version  Show the SDK version and exit.
  --help     Show this message and exit.

Commands:
  generate  Generate the typed module from the configured projects' schemas.
  init      Select projects to manage and write optixlog.toml (idempotent).
  login     Authenticate with an API key and persist the credential.
  whoami    Show the globally saved login (~/.optixlog/credentials.toml).

Error and exit-code convention

Every command body runs inside a shared error handler. When an error occurs:

• The message is printed as error: <message> to stderr in red.
• The process exits with code 1.

Errors that trigger this include OptixLogError, ConfigError, CredentialsError, and ContractError. Success messages print to stdout in green and exit with code 0.

The one exception is generate --check: a stale output file prints a message to stderr and exits 1 directly — this is not treated as an error, but as an expected CI guard signal.

The canonical developer flow

# 1. Authenticate once
optixlog login

# 2. Select projects and write optixlog.toml (commit this file)
optixlog init

# 3. Fetch schemas and emit the typed module
optixlog generate

After generate, your repo contains optixlog_gen.py (or a package directory if you chose module_style = "package"). Import OptixClient, Projects, and your node classes from it:

from optixlog_gen import OptixClient, Projects, SimulationNode

client = OptixClient()
client.project(Projects.GRATING_COUPLER_LAB).ingest(
    data=SimulationNode(config={}, solver="fdtd"),
    prompt="Simulated a grating coupler.",
)