Reference R1

CLI reference

Every command the Typer-based CLI exposes. Commands that touch Oracle all honour the same DSN resolution rules — described at the bottom.

Info commands

onnx2oracle version
onnx2oracle presets

version prints the package version. presets prints the five registered models with their Oracle names, HF repos, and dimensions.

load

The primary command. Two shapes — preset or HuggingFace repo.

onnx2oracle load <preset> [--target local | --dsn user/pw@host:port/service]
                         [--force] [--name ORACLE_NAME] [--cache-dir PATH]

onnx2oracle load --from-huggingface <hf/repo> --pooling {mean,cls}
                 [--normalize/--no-normalize] [--max-length 512]
                 --dims 384 --name ORACLE_NAME
                 [--target local | --dsn ...]

Flags

Flag	Meaning
<preset>	One of the five registered names. `onnx2oracle presets` shows the list.
--from-huggingface	Alternative to preset. Fully-qualified HF repo (e.g. `BAAI/bge-large-en-v1.5`).
--target local	Use the local Docker DSN `system/${ORACLE_PWD:-onnx2oracle}@localhost:${ORACLE_PORT:-1521}/FREEPDB1`.
--dsn	Explicit connection string. See DSN resolution.
--force	Drop and reload if the model name already exists in `user_mining_models`.
--name	Override the Oracle mining-model identifier. Required for `--from-huggingface`.
--cache-dir	Where to cache the HuggingFace download. Defaults to `~/.onnx2oracle/cache`.
--pooling	`mean` or `cls`. Custom loads only — presets encode this.
--normalize / --no-normalize	Append L2 normalization. Default on.
--max-length	Token truncation limit. Default 512.
--dims	Asserted output dimension. Custom loads only.

preflight

onnx2oracle preflight [--target local | --dsn ...]

Checks the database before a model upload. It connects, prints the database banner, confirms SYS.DBMS_VECTOR is valid, confirms the SQL function catalog includes VECTOR_EMBEDDING, checks mining-model privileges, checks EXECUTE access to DBMS_VECTOR, and confirms user_mining_models is visible.

Exit code 0 means the target is ready for DBMS_VECTOR.LOAD_ONNX_MODEL. Non-zero output names the missing package, function, privilege, or catalog view.

verify

onnx2oracle verify [--target local | --dsn ...] [--name ORACLE_NAME]

Runs three checks against the named model (or the last one loaded in the session):

VECTOR_EMBEDDING returns a vector of the expected dimension.
The vector is float32.
cosine(v, v) = 1.000 on a deterministic string.

Exit code 0 on success, non-zero otherwise.

docker

onnx2oracle docker up [--wait] [--wait-timeout 600] [--wait-interval 5]
onnx2oracle docker down [--volumes]
onnx2oracle docker logs [-f]

Thin wrapper around docker compose pointed at the bundled compose file. up --wait runs a SQL readiness probe inside the container until it succeeds or --wait-timeout elapses — see #docker-timeout.

The bundled compose file honors ORACLE_PWD, ORACLE_PORT, and ORACLE_IMAGE. Use ORACLE_PORT=1524 when 1521 is already occupied, or ORACLE_IMAGE=container-registry.oracle.com/database/free:latest-lite to try the smaller Oracle Free image without editing YAML.

logs -f tails Oracle's alert log. Useful when the container comes up but something inside the database doesn't.

config

onnx2oracle config show
onnx2oracle config set key=value

show dumps the effective TOML at ~/.onnx2oracle/config.toml. set writes a single key. Typical keys:

dsn — persistent DSN in the [default] table; wins over --target local but loses to --dsn and ORACLE_DSN.
cache_dir — override ~/.onnx2oracle/cache.
hf_token — persisted HuggingFace token (prefer HF_TOKEN env if you don't want it on disk).

DSN resolution

Every Oracle-bound command resolves a DSN by this order, first match wins:

#	Source	Example
1	`--dsn` flag	--dsn admin/pw@...
2	`ORACLE_DSN` env var	export ORACLE_DSN=...
3	`~/.onnx2oracle/config.toml` `dsn` in `[default]`	config set dsn=...
4	`--target local`	system/${ORACLE_PWD:-onnx2oracle}@localhost:${ORACLE_PORT:-1521}/FREEPDB1
5	Interactive prompt	CLI asks stdin

One exception. docker up/down/logs don't need a DSN — they talk to Docker directly. Every other command walks the table above.

Custom models Troubleshooting