CLI reference

Command syntax, options, environment variables, output, and exit status for Olyx.

Command syntax, configuration selection, output formats, and exit status.

Synopsis

olyx <command> [arguments] [options]

Command	Description
`init`	Generate configuration and a request example
`serve`	Start the application HTTP endpoint
`route`	Send a JSON request through a configured model route
`replay`	Re-execute a recorded request or compare model aliases
`debug`	Inspect a local trace or list recent traces
`doctor [--probe]`	Check local setup and optionally probe provider connectivity
`check FILE`	Validate a configuration file without calling a provider
`inspect`	Report the configuration path, file availability, storage mode, and version
`help [COMMAND]`	Print general help or help for init, serve, route, replay, debug, check, doctor, or inspect
`--version`, `-V`	Print the installed version

Global options

Option	Behavior
`--config FILE`	Select the local configuration for init, serve, route, replay, debug, doctor, or inspect
`--dry-run`	Preview a route request or replay parameters without calling providers or creating traces
`--help`, `-h`	Print general help when used before the command

check takes its configuration as a positional argument: olyx check olyx.json. For command help, use olyx help COMMAND. init, serve, route, replay, debug, and doctor also accept --help after the command.

Configuration resolution

Runtime commands select a configuration in this order:

--config FILE
The OLYX_CONFIG environment variable
olyx.json in the current working directory

export OLYX_CONFIG=./examples/olyx.json
olyx inspect
olyx check "$OLYX_CONFIG"
olyx debug

inspect reports whether the file exists; it does not validate its contents or test provider connectivity. Run check to validate configuration. Provider keys are read from the environment variables named by each route’s api_key_env field.

Environment variables

Variable	Purpose
`OLYX_CONFIG`	Default configuration file path
`HF_TOKEN`	Provider credential used by the Hugging Face preset
`OPENAI_API_KEY`	Provider credential used by the OpenAI preset
`OLYX_SERVER_API_KEY`	Application bearer token for `serve`; required for non-loopback binding

Custom routes name their credential variable with api_key_env. The HTTP server loads credentials at startup; restart it after changing provider keys.

Output and exit status

Successful commands write to standard output. Route, replay, debug, doctor, and inspect return JSON; streaming route returns newline-delimited JSON. Check, help, and version return text. Errors are written to standard error.

Status	Meaning
`0`	Command completed successfully
`1`	Runtime failure, including configuration loading, storage, or provider errors
`2`	Invalid command or arguments
`130`	Route or replay interrupted with Ctrl-C; cancellation traces are finalized before exit

Capture stdout and stderr separately in scripts. A successful process exit indicates execution completed; it does not evaluate model quality. CLI output masks recognizable credentials. Recorded request and response content remains in local storage.

olyx route --input request.json > result.json 2> error.log