Configuration¶

Settings live in .ontoenv/config.json and are re-applied by every command and every reopen. They can be set at init time, changed with ontoenv config, passed to a Python lifecycle method, or changed at runtime with a set_* method.

Settings¶

Key	Type	Default	CLI flag	Python argument
`locations`	list[path]	`[]`	`init <DIR>...`	`search_directories=`
`includes`	list[glob]	`['.ttl','.xml','*.n3']`	`-i`, `--includes`	`includes=`
`excludes`	list[glob]	`[]`	`-e`, `--excludes`	`excludes=`
`include_ontologies`	list[regex]	`[]`	`--include-ontology`	`include_ontologies=`
`exclude_ontologies`	list[regex]	`[]`	`--exclude-ontology`	`exclude_ontologies=`
`offline`	bool	`false`	`-o`, `--offline`	`offline=`
`strict`	bool	`false`	`--strict`	`strict=`
`require_ontology_names`	bool	`false`	`--require-ontology-names`	`require_ontology_names=`
`use_cached_ontologies`	bool	`false`	—	`use_cached_ontologies=`
`remote_cache_ttl_secs`	int	`86400`	`--remote-cache-ttl-secs`	`remote_cache_ttl_secs=`
`resolution_policy`	string	`"default"`	`-p`, `--policy`	`resolution_policy=`
`temporary`	bool	`false`	`-t`, `--temporary`	`temporary=`
`root`	path	`"."`	—	`root=`

Notes

includes / excludes: gitignore-style globs matched against file paths, before parsing. A bare directory expands to dir/**.
include_ontologies / exclude_ontologies: Regular expressions matched against ontology IRIs, after parsing. Includes act as a whitelist; excludes run last.
resolution_policy: Which definition wins when several files declare the same ontology IRI. "default" prefers the first registered, "latest" the most recently updated, "version" the highest version property.
use_cached_ontologies: When enabled, discovery is skipped at init time; the environment fills only from explicit add and update calls.
remote_cache_ttl_secs: How long a cached remote ontology is trusted before update re-fetches it.

Setting values from the CLI¶

$ ontoenv config list
$ ontoenv config get locations

Scalar keys use set and unset:

$ ontoenv config set offline true
$ ontoenv config set strict false
$ ontoenv config set require_ontology_names true
$ ontoenv config set resolution_policy latest
$ ontoenv config set remote_cache_ttl_secs 604800
$ ontoenv config unset remote_cache_ttl_secs

set accepts exactly those five keys. List keys use add and remove:

$ ontoenv config add locations ./more-ontologies
$ ontoenv config remove locations ./old-path
$ ontoenv config add includes '*.n3'
$ ontoenv config add excludes 'vendor'

add/remove accept locations, includes, and excludes. include_ontologies and exclude_ontologies have no config subcommand support — pass the flags on a command, or edit .ontoenv/config.json.

Setting values from Python¶

At open time, any key can be passed as a keyword argument:

env = OntoEnv.connect(
    "./ontology-env",
    search_directories=["./ontologies"],
    includes=["*.ttl"],
    exclude_ontologies=[r"experimental"],
    offline=True,
    remote_cache_ttl_secs=604800,
)

At runtime, the set_* methods change and persist a setting on an open, writable environment:

env.set_offline(True)
env.set_strict(False)
env.set_require_ontology_names(True)
env.set_use_cached_ontologies(True)
env.set_remote_cache_ttl_secs(604800)
env.set_resolution_policy("latest")

Each has a matching getter — is_offline(), is_strict(), requires_ontology_names(), uses_cached_ontologies(), remote_cache_ttl_secs(), resolution_policy().

Override rules on reopen¶

When reopening an existing environment:

Omitting an option keeps the saved value.
Passing a value overrides it. False, "default", and [] are genuine overrides, not “unset”.
A writable connection persists the override; a read-only one applies it to that session only.

OntoEnv.connect("./env")                          # everything as saved
OntoEnv.connect("./env", strict=True)             # override one setting
OntoEnv.connect("./env", search_directories=[])   # explicitly clear

On the CLI, boolean flags take explicit values so a saved true can be turned off:

$ ontoenv update --offline=false --strict=false

Changing configuration never triggers a scan or re-ingestion. Runtime modes apply immediately; changed discovery paths and filters apply on the next update().

Environment variables¶

ONTOENV_DIR: Path to the environment to use, overriding the walk-up-from-cwd search. It may name the .ontoenv directory itself or the root containing it.
RUST_LOG: Standard Rust log filter. -v sets it to info and --debug to debug.