OARepo CLI

oarepo-cli is a command-line tool for scaffolding and developing OARepo repositories and libraries.

It provides three things:

• new — scaffold a brand-new repository from a copier template
• repository — manage an existing repository instance (install, run, test, models, ...)
• library — develop an OARepo library package (models, modules, extensions)

Table of Contents

• New Repository
• Repository Tools
• Library Development Tools
• Configuration
• Exit Codes
• License

New Repository

At first, make sure that you have uv installed. See docs.astral.sh for installation instructions.

Then, uvx oarepo-cli new <name> scaffolds a new repository from a copier template into ./<name>.

uva oarepo-cli new my-repo

What it does:

1. Renders the template into ./<name>
2. Generates a self-signed development TLS certificate/key pair (docker/development.crt/.key)
3. Clears out any stale Docker containers left over from a previous attempt at the same name
4. Initializes a git repository with an initial commit (skipped in CI, or if git isn't installed)
5. Adds a run.sh script for installing and running the repository

Repository Tools

Commands for managing an existing repository instance, run from inside the repository directory.

Every command accepts --quiet/-q to suppress subprocess output; only additional options are listed below.

repository install

Installs the repository into its virtual environment and configures Invenio.

oarepo-cli repository install

1. Syncs the virtual environment with uv sync
2. Copies the translation overlay into site-packages
3. Resolves and creates the Invenio instance directory, symlinking invenio.cfg
4. Runs invenio-cli install (assets, database tables, etc.)
5. Writes local service ports to .invenio.private
6. Compiles backend translations

repository upgrade

Removes the virtual environment, uv.lock, and uv cache, then reinstalls from scratch. Use after changing OARepo/RDM version pins or when the environment needs a clean rebuild.

oarepo-cli repository upgrade

repository services

Passthrough to invenio-cli services <subcommand>: extra arguments/flags are forwarded verbatim, and --help shows invenio-cli's own help.

oarepo-cli repository services setup
oarepo-cli repository services start
oarepo-cli repository services stop
oarepo-cli repository services destroy

repository model

Creates and updates record models via copier, rendering the model template into models/<name>/. The template/version are configured in pyproject.toml ([tool.oarepo-cli.model]) or via OAREPO_MODEL_TEMPLATE_URL/OAREPO_MODEL_TEMPLATE_VERSION — not as CLI flags.

oarepo-cli repository model create <name> [config_file]
oarepo-cli repository model update <name> [answers_file]

• create <name> [config_file]: renders the template into models/<name>/. If config_file (YAML) is given, it seeds all answers and must include model_name itself; otherwise only model_name is passed and the template's own defaults apply. Reinstalls the repository afterward if a virtual environment already exists.
• update <name> [answers_file]: updates an existing model from its recorded .copier-answers.yml, or from answers_file if given. Requires a clean, git-tracked repository; conflicts are written inline for review via git diff.

repository local

Manages locally-developed packages as editable [tool.uv.sources] entries in pyproject.toml — for developing a dependency (e.g. a custom extension) alongside the repository. Both subcommands edit pyproject.toml in place and trigger a full repository upgrade (without clearing the uv cache).

oarepo-cli repository local add <path>
oarepo-cli repository local remove <name>
oarepo-cli repository local remove --all

• add <path>: adds the package at <path> (which must have its own pyproject.toml) as an editable source and appends it to [project].dependencies. Re-adding an already-present package updates its entry in place.
• remove <name> / remove --all: removes one or all local packages from [tool.uv.sources]/[project].dependencies. --all only touches entries added via add and upgrades once for all of them.

repository run

Starts the development server: starts Docker services (unless --no-services), then replaces the current process with invenio-cli run (or, with --no-celery, the venv's own invenio run directly). A terminal Ctrl+C hits invenio/invenio-cli directly. Services are not stopped when the server exits — run repository services stop explicitly.

oarepo-cli repository run
oarepo-cli repository run --no-celery -- -p 5001

Extra arguments (e.g. -p 5001) are forwarded to the underlying invenio-cli run/invenio run.

repository shell

Opens an interactive bash shell with the virtual environment activated, resolving service connection details from invenio.cfg/.invenio.private. Replaces the current process — it never returns.

oarepo-cli repository shell
oarepo-cli repository shell --no-services

repository cli / repository invenio

Pure passthroughs that replace the current process, so --help and the exit code are exactly the wrapped tool's own. cli runs invenio-cli; invenio runs the venv's own bare invenio binary directly.

oarepo-cli repository cli services status
oarepo-cli repository invenio db upgrade

repository lint / format / check

Runs ruff, a license-header check, a from __future__ import annotations check, and ty, across every module directory declared in [tool.uv.build-backend] (or src/, if used instead).

oarepo-cli repository lint
oarepo-cli repository format
oarepo-cli repository check

• lint runs everything in order, stopping at the first failure, and auto-fixes by default (--no-fix for report-only).
• format runs ruff format only, and rewrites files by default (--no-fix for ruff format --check).
• check is the read-only equivalent of both combined (never modifies files) — the exit code is that of the first failing check. Still generates .ruff.toml/ty.toml config files in the project root.

repository jslint / jstest

jslint runs ESLint and Prettier on the repository's JavaScript files (skipped if no package.json exists at the root). jstest runs Jest via invenio webpack run test, across every registered invenio_assets.webpack entry point; it requires the repository to already be installed.

oarepo-cli repository jslint
oarepo-cli repository jstest

repository test

Runs the pytest suite. Docker services are started first unless --no-services (unlike other commands, they are never stopped afterward). pytest/pytest-cov are installed on demand if missing, since a fresh repository has no "tests" extra of its own.

oarepo-cli repository test
oarepo-cli repository test --with-coverage
oarepo-cli repository test -v -k test_specific

Extra arguments are passed directly to pytest.

repository translations

oarepo-cli repository translations          # extract, merge, compile (backend + JS)
oarepo-cli repository translations compile  # backend only, via invenio-cli

repository index rebuild

Destroys and re-creates the search index, then rebuilds all records and custom fields.

oarepo-cli repository index rebuild

repository reset

Destroys Docker services, removes the virtual environment/uv.lock/.invenio.private, cleans the uv cache, reinstalls, sets up services again, and creates a demo admin user (user@demo.org, password from DEMO_USER_PASSWORD, default 123456).

oarepo-cli repository reset

Prompts for confirmation (exactly yes) since this purges all existing data in your containers. Anything else cancels without error.

repository info

Shows the resolved Python version and discovered record models.

oarepo-cli repository info

Library Development Tools

Commands for developing an OARepo library package, run from inside the library directory.

Every command accepts --quiet/-q to suppress subprocess output; only additional options are listed below.

library venv / install / upgrade

venv (aliased as install) creates or verifies the virtual environment and syncs dependencies; upgrade stops services, cleans the uv cache, and recreates the venv from scratch.

oarepo-cli library venv
oarepo-cli library venv --force
oarepo-cli library upgrade

library test

oarepo-cli library test
oarepo-cli library test --with-coverage -x -k test_specific

Extra arguments are passed directly to pytest.

library start / stop

Starts or stops the Docker services (PostgreSQL, OpenSearch, Redis, RabbitMQ, MinIO) configured via [tool.oarepo-cli.services] or OAREPO_SERVICES_*, writing connection details to .env-services.

oarepo-cli library start
oarepo-cli library stop

library lint / format / check

Runs ruff, a license-header check, a from __future__ import annotations check, and ty on the library's source.

oarepo-cli library lint
oarepo-cli library format
oarepo-cli library check

• lint runs everything in order, stopping at the first failure, and auto-fixes by default (--no-fix for report-only). The license-header and future-annotations checks never modify files — use license-headers for those.
• format runs ruff format only, and rewrites files by default (--no-fix for ruff format --check).
• check is the read-only equivalent of both combined — safe for CI.

library shell

Opens an interactive bash shell with the venv activated and .env-services loaded. Replaces the current process.

oarepo-cli library shell
oarepo-cli library shell --skip-services

library invenio

Runs invenio CLI commands in the venv, with .env-services loaded.

oarepo-cli library invenio db upgrade
oarepo-cli library invenio users create admin@example.com --password 123456 --active

library translations

Extracts and compiles translations via oarepo-tools make-translations. Extra arguments are forwarded to it verbatim.

oarepo-cli library translations

library license-headers

Adds an SPDX/MIT license header to any Python file that doesn't already have one.

oarepo-cli library license-headers
oarepo-cli library license-headers --organization "My Organization"

library jslint / jstest

jslint runs ESLint and Prettier on JavaScript files (skipped if no package.json exists). jstest runs Jest via invenio webpack run test.

oarepo-cli library jslint
oarepo-cli library jstest

library oarepo-versions

Prints the OARepo/Python/Node versions detected from pyproject.toml's dependency constraints and system availability, as JSON:

$ oarepo-cli library oarepo-versions
{"oarepo_versions": ["14"], "python_versions": ["3.14"], "node_versions": ["24", "22"]}

• OARepo versions: Extracted from oarepo constraints in [project].dependencies/[project.optional-dependencies], sorted highest-first. Commands that need a single version (venv, test, ...) use the highest one; override with OAREPO_VERSION.
• Python versions: Compatible versions from requires-python constraint that are available on the system.
• Node.js versions: Available Node.js major versions detected on the system (empty array if Node.js is not installed).

library clean

Stops services, then removes the virtual environment, uv.lock, and .env-services. Idempotent.

oarepo-cli library clean

Configuration

Settings are resolved with this precedence: defaults < pyproject.toml < environment variables < CLI flags.

Example pyproject.toml:

[tool.oarepo-cli.venv]
path = ".venv"

[tool.oarepo-cli.services]
db = "postgresql"
search = "opensearch"
cache = "redis"
mq = "rabbitmq"
s3 = "minio"

[tool.oarepo-cli.license]
organization = "Your Organization"

Exit Codes

• 0 — success.
• 1 — a failure, e.g. a subprocess exited non-zero, or the project context couldn't be discovered (no pyproject.toml).
• 2 — a usage error (missing/invalid arguments or options), reported before anything runs.
• Passthrough commands (repository cli/invenio/services <subcommand>, repository run's server) exit with whatever the wrapped tool itself returns, not collapsed to 0/1.

repository reset is the one exception: 0 covers both a completed reset and the user cancelling the confirmation prompt.

License

MIT License — see LICENSE for details.

Copyright © 2026 CESNET z.s.p.o.