Exit Codes
CLI exit codes and the complete list of error messages printed to stderr by the OptixLog CLI.
The optixlog CLI uses a small, consistent set of exit codes and always prints errors to stderr with the prefix error: in red.
Exit code table
| Code | Meaning |
|---|---|
0 | Success. The command completed without error. |
1 | Error — a problem was encountered and the operation did not complete. Also used by generate --check when the output file is stale (not actually an error, but a signal for CI). |
There are only two codes. All failures — authentication errors, missing config, bad input, contract violations — exit 1.
generate --check and exit 1
optixlog generate --check exits 1 when the existing output file does not match what would be generated from the current schema. This is intentional: it lets CI pipelines fail when generated bindings are out of date. It is not an error condition in the usual sense — it just means optixlog generate needs to be re-run.
Error message format
Every error message is printed to stderr as:
error: <message>The text appears in red via Typer's secho. No stack traces are printed to the user; they are swallowed by the _handle_errors() context manager that wraps each command body.
Common error messages
The messages below are sourced directly from src/optixlog/_cli/app.py, _credentials.py, and _cli/config.py.
Authentication and credentials
| Message | When it occurs |
|---|---|
an API key is required (pass --api-key, set OPTIXLOG_API_KEY, or enter it when prompted). | login was run with --no-input but no key was supplied via flag or env var. |
an API key is required (run 'optixlog login', pass --api-key, or set OPTIXLOG_API_KEY). | init was run with --no-input and no key is available from any source. |
Project selection
| Message | When it occurs |
|---|---|
no accessible projects for this key. | The API key is valid, but the server returned zero projects the key can access. |
no projects selected. | The interactive project selection prompt was completed without choosing any project, or --project flags matched nothing after filtering. |
no accessible project matches '<token>'. | A value passed to --project did not match any project id or name (case-insensitive) in the accessible list. |
pass --all or --project in non-interactive use (--no-input). | init was called with --no-input but without --all or at least one --project flag. |
Configuration
| Message | When it occurs |
|---|---|
no optixlog.toml found; run 'optixlog init' first. | generate could not find optixlog.toml by walking up from the current directory. |
<path>: no [[projects]] selected. | optixlog.toml was found but has no [[projects]] entries. |
Generate --check
| Message | When it occurs |
|---|---|
<path> is out of date; re-run 'optixlog generate'. | generate --check found that the existing file does not match what would be generated. Exits 1. |
The success message for --check (<path> is up to date.) is printed in green and exits 0.
Contract and schema errors
These arise from invalid or unexpected schema contract content and are instances of ContractError or TypeMapError, both caught by _handle_errors():
| Message pattern | Cause |
|---|---|
unsupported schema_version: <n> | schema_version is not 1. |
duplicate project id: <id> | Two projects in projects share the same id. |
project_node_types references unknown project id: <id> | A key in project_node_types is not in projects. |
project_node_types references unknown node type: <name> | A value in project_node_types is not in node_types. |
project <id> has no node types in project_node_types | A project was listed with an empty node type array. |
node type '<name>' has conflicting field definitions | The same node type name appeared twice in node_types with different fields. |
enum field '<name>' has no enum values | A field with type: "enum" has no enum array. |
unsupported field type: '<type>' | An unrecognized type string was encountered in a field definition. |
Behavior reference by command
- Exit
0: authenticated and credential saved successfully. - Exit
1: missing API key, network/auth failure, fixture not found, orCredentialsErrorwriting the file.
- Exit
0:optixlog.tomlwritten (or already exists and--forcewas not passed). - Exit
1: no accessible projects, no projects selected, invalid--projecttoken, missing API key, or network failure.
- Exit
0: file written successfully, or--checkand file is up to date, or--dry-runand source printed. - Exit
1:optixlog.tomlnot found, no[[projects]], network/auth failure, or--checkand file is stale.
- Exit
0: credential found and displayed (optionally validated). - Exit
1: not logged in, or--validateand the key is no longer valid.
Generated Module Anatomy
A section-by-section walk-through of optixlog_gen.py — what each block contains, what is generated vs hand-written, and how the static typing mechanism enforces per-project node constraints.
Glossary
Definitions for every term used across the OptixLog SDK and CLI documentation — organization, project, workflow node, codegen, OptixClient, and more.