optixlog generate

Fetch project schemas and emit a byte-deterministic typed Python module. Supports write, dry-run, and check modes.

optixlog generate reads optixlog.toml, fetches the schema for each configured project, and emits a fully-typed Python module (by default optixlog_gen.py). The output is byte-deterministic — re-running with the same schemas produces an identical file.

Synopsis

optixlog generate [OPTIONS]

Flags

Prop

Type

Config discovery

If --config-path is not provided, generate walks up from the current working directory, checking each directory for optixlog.toml. This lets you run the command from any subdirectory of a project.

If no config file is found, the command exits with:

error: no optixlog.toml found; run `optixlog init` first.

Control flow

Locate and load config

Finds optixlog.toml (via --config-path or walk-up). Loads it and extracts the list of project ids from [[projects]].

If the projects list is empty:

error: ./optixlog.toml: no [[projects]] selected.

Resolve credentials

Base URL: --base-url → the config's api_base_url.

API key: OPTIXLOG_API_KEY env → --api-key → stored profile (--profile).

Fetch schemas

Calls backend.fetch_schemas(project_ids) for every project id in the config. With --fixture, this reads the local fixture and narrows it to the requested ids. With a live server, it queries v0.codegen.schema.

If a requested project id is not present in the fixture, the command exits with:

error: unknown project id(s) in schema: proj_missing_id

Render the module

Renders the typed Python source with render_module(contract). The render is deterministic — given the same schema, it always produces the same bytes.

Dispatch on mode

The three modes are checked in this order:

--dry-run (checked first, wins over --check): Prints the source to stdout (no trailing newline) and returns.

--check: Reads the existing file (if it exists) and compares it to the freshly rendered source.

If equal: prints <path> is up to date. to stdout and exits 0.
If different (or file does not exist): prints <path> is out of date; re-run \optixlog generate`.` to stderr and exits 1.

Default (write): Writes the source to the output path and prints:

Generated ./optixlog_gen.py for 2 project(s).

The three modes

optixlog generate

Writes optixlog_gen.py (or the configured output path) with the freshly rendered source. Overwrites the existing file if present. Exits 0.

optixlog generate --dry-run

Prints the generated Python source to stdout without writing any file. Useful for inspecting output or piping to another tool.

# Preview the output
optixlog generate --dry-run | head -50

# Diff against the committed file
diff optixlog_gen.py <(optixlog generate --dry-run)

optixlog generate --check

Compares a fresh render to the on-disk file. Exits 1 if stale (including when the file does not exist). Never writes. Use this in CI to guard against committed bindings that are out of date.

# In CI — fail the job if bindings are stale
optixlog generate --fixture tests/fixtures/schema.sample.json --check

Output path resolution

The output path is resolved in this order:

--output flag (if given).
[codegen].output_path from optixlog.toml.

A relative path is resolved against the config file's directory, not the current working directory. This means if optixlog.toml is at /repo/optixlog.toml and output_path = "optixlog_gen.py", the file is written at /repo/optixlog_gen.py regardless of which subdirectory you run the command from.

Determinism

The generated module is byte-deterministic: running generate twice with the same schemas produces identical bytes. There are no timestamps or random values in the output. This makes it safe to commit optixlog_gen.py and use --check in CI as a drift detector.

Example invocations

# Write the module (default)
optixlog generate

# Offline with fixture
optixlog generate --fixture tests/fixtures/schema.sample.json

# Check for drift in CI (offline)
optixlog generate --fixture tests/fixtures/schema.sample.json --check

# Dry-run: preview without writing
optixlog generate --dry-run

# Override output path
optixlog generate --output src/optixlog_gen.py

# Use a non-default profile
optixlog generate --profile ci

# Point to a config in a non-standard location
optixlog generate --config-path /path/to/project/optixlog.toml

Errors

Condition	Message	Exit code
No `optixlog.toml` found	`error: no optixlog.toml found; run \`optixlog init` first.`	1
Config has no `[[projects]]`	`error: ./optixlog.toml: no [[projects]] selected.`	1
Unknown project id in fixture	`error: unknown project id(s) in schema: <ids>`	1
Output is stale (`--check`)	`<path> is out of date; re-run \`optixlog generate`.` → stderr	1
Missing or invalid API key	`error: no API key available; pass api_key=..., set OPTIXLOG_API_KEY, or run \`optixlog login`.`	1

--dry-run takes precedence over --check

When both --dry-run and --check are passed, --dry-run wins. The source is printed to stdout and the command exits 0.

optixlog generate

On this page