Getting Started

Everything you need to set up a workspace, control what gets loaded, and keep your cached ontologies fresh — using the CLI, the Python package, or both.

Install

1. Install the CLI (Rust) — requires a Rust toolchain; the binary is published on crates.io.

cargo install ontoenv-cli

# or build from this workspace after cloning:
cargo build -p ontoenv-cli --release

2. Install the Python package — pre-built wheels on PyPI; no Rust toolchain needed.

pip install ontoenv

# To build from source (e.g., after cloning):
cd python && uv run maturin develop

Initialize a workspace

ontoenv stores its metadata under .ontoenv/. Run init and pass the directories you want scanned:

# Discover every ontology under the current directory
ontoenv init .

# Create an empty container (add ontologies later with ontoenv add)
ontoenv init

# Seed from multiple directories at once
ontoenv init ./ontologies ./models

💡

Re-running init? Pass --overwrite to rebuild the environment in place. Every command walks up from the current directory to find .ontoenv/ unless ONTOENV_DIR is set.

Add and refresh ontologies

Once the workspace exists, register individual files or URLs and keep them fresh:

# Add a single ontology (fetches owl:imports by default)
ontoenv add ./ontologies/site.ttl

# Add without following imports
ontoenv add ./ontologies/site.ttl --no-imports

# Refresh stale remote cache entries
ontoenv update

# Force every ontology to re-download
ontoenv update --all

Use ontoenv list ontologies or ontoenv dump to inspect what is currently cached.

Control discovery scope

Two independent filter layers govern what gets pulled in:

Filter layers

• -i/--includes and -e/--excludes — gitignore-style globs on file paths. Bare directories (e.g. lib/tests) auto-expand to lib/tests/**.
• --include-ontology / --exclude-ontology — regex patterns run against ontology IRIs after parsing. Includes act as a whitelist; excludes prune what slips through.

ontoenv init ontologies \
  --includes '*.ttl' \
  --exclude-ontology 'experimental' \
  --include-ontology '^https://example\.com/'

Settings are saved into .ontoenv/config.json and re-applied by every subsequent command.

Cache strategy and TTL

Remote ontologies are stored on disk. Two knobs control how aggressively they are refreshed:

Cache options

• use_cached_ontologies — when enabled, discovery is skipped at init time and the environment only fills when you explicitly call add or update.
• --remote-cache-ttl-secs — maximum age (seconds) of a cached remote ontology before update re-fetches it. Default: 86,400 (24 hours).

# Keep cached copies for a week before refreshing
ontoenv update --remote-cache-ttl-secs 604800

# Persist these as defaults
ontoenv config set remote_cache_ttl_secs 604800
ontoenv config add locations ./ontologies

Python quickstart

The Python API exposes the same configuration surface as the CLI:

from ontoenv import OntoEnv

env = OntoEnv(
    path=".",                    # look for (or create) .ontoenv here
    recreate=True,               # create/overwrite metadata
    search_directories=["."],    # scan the current project
    includes=["*.ttl", "*.xml"],
    include_ontologies=[r"^https://example\.com/"],
    exclude_ontologies=[r"experimental"],
    offline=True,
    use_cached_ontologies=False,
    remote_cache_ttl_secs=86400,
)

env.update(all=True)

# Retrieve a merged graph of an ontology and all its transitive imports
g, imported = env.get_closure("https://example.com/myOntology")
print(f"Merged {imported} imports, {len(g)} triples total")

Pass use_cached_ontologies=True to start with an empty container that only fills when you explicitly call add or update.

Building the docs

The documentation lives under docs/ with its own pyproject.toml:

cd docs
uv sync                              # install Sphinx + theme
uv run sphinx-build -M html . _build
open _build/html/index.html

Helper scripts in the repo root:

./builddocs          # sync deps, build the extension, render HTML
./builddocs llms     # also render docs/_build/llms.txt for LLM ingestion