Installation

Marivo requires Python 3.12 or newer.

Install the base library from PyPI:

pip install marivo

Install the backend extra that matches the datasource you want to query:

Backend	Install command
DuckDB	pip install "marivo[duckdb]"
MySQL	pip install "marivo[mysql]"
Postgres	pip install "marivo[postgres]"
ClickHouse	pip install "marivo[clickhouse]"
Trino	pip install "marivo[trino]"
All packaged backends	pip install "marivo[all]"

Initialize a project

Scaffold a new project in the current directory with the CLI:

marivo init

marivo init creates the project skeleton and installs the Marivo agent skills:

Path	Purpose
marivo.toml	Project manifest. The project name defaults to the directory name.
models/	Where you author datasource and semantic declarations.
.marivo/	Project-local state: sessions, evidence, and cached metadata.
.claude/skills/marivo-semantic, .claude/skills/marivo-analysis	Marivo skills for Claude Code (symlinked into the project).
.codex/skills/marivo-semantic, .codex/skills/marivo-analysis	The same skills for Codex.

init is idempotent: existing files are left untouched and reported as skipped, so it is safe to re-run — for example after upgrading to a release that ships updated skills. Re-running only adds what is missing. Use marivo init --force to delete the artifacts above and recreate them from scratch.

Note

init refuses to silently skip a marivo.toml that contains invalid TOML — fix or remove it, or pass --force. Skill links are best-effort: if your platform cannot create a symlink, init prints a warning and continues.

The result is a ready-to-author project:

your-project/
  marivo.toml
  models/
  .marivo/
  .claude/skills/   # marivo-semantic, marivo-analysis
  .codex/skills/    # marivo-semantic, marivo-analysis

Add .marivo/ to .gitignore; version-control marivo.toml and models/ (see Quick Start).

Deploy and develop

Marivo is a Python library, not a hosted service. Deploy a Marivo project by installing the library where the agent runs, checking in datasource and semantic declarations, and providing datasource secrets through environment variables referenced by *_env fields.

For local development from this repository:

python3 -m venv .venv
.venv/bin/pip install -e ".[dev,duckdb,trino]"
.venv/bin/python -c "import marivo; print(marivo.__name__)"