olyx route

Send a JSON request to a model and save a local trace of the request, response, and each provider attempt.

Synopsis

olyx route [--model ALIAS] [--input FILE|-] [--config FILE] [--dry-run]

Options

Option	Description
--model ALIAS	Override the request’s model with an alias from the configuration
--input FILE	Read a JSON request from a UTF-8 file
--input -	Read from standard input; this is the default
--config FILE	Select local routes and trace storage
--dry-run	Load configuration and parse the request, then print the request without executing it

--dry-run reads the configuration and checks that the input is a JSON object. It does not run all request checks, test the API key, or contact the provider. Send a real request to test the full connection.

Send a request

Save this as request.json, with fast defined in olyx.json:

{
  "model": "fast",
  "messages": [{"role": "user", "content": "Explain ordered provider fallbacks in one sentence."}]
}

olyx check olyx.json
olyx route --input request.json

Without streaming, Olyx prints a JSON object containing trace_id and output. Use that ID to inspect or replay the request. For example:

{
  "trace_id": "TRACE_ID",
  "output": {"choices": [{"message": {"role": "assistant", "content": "Example response"}}]}
}

Read from a pipe or choose another model

cat request.json | olyx route --model quality
olyx route --input request.json --model fast --dry-run

--model must name a route in your configuration. To use a different provider model, add it to the configuration first. The quality example above assumes you have already configured that alias.

Fallback behavior

The CLI includes examples/fallbacks.json, where fast tries OpenAI first and Hugging Face second. Replace its model placeholder and export OPENAI_API_KEY and HF_TOKEN, then run:

olyx check examples/fallbacks.json
olyx route --config examples/fallbacks.json --input examples/request.json

Olyx tries providers in the order listed. It tries the next provider after a connection failure, HTTP 429, or a provider 5xx response. An invalid API key or request stops the route. Use olyx debug TRACE_ID to see which providers were tried.

An interrupted streaming response stops the route. Olyx does not switch providers after partial output has reached the terminal.

Request controls

A request needs a model alias and a messages array with at least one message. stream must be a boolean. Output limits must be positive integers and cannot exceed the configured output-token limit. Unknown aliases fail with unknown_model.

Use streaming for incremental output and provider protocols for compatible endpoints and plugins. Configuration defaults and validation are documented in the configuration reference.