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 --version
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; local telemetry defaults to `enabled = "on"`.
`models/`	Where you author datasource and semantic declarations.
`.marivo/`	Project-local state: sessions, evidence, and cached metadata.
`.agents/skills/marivo-semantic`, `.agents/skills/marivo-analysis`	Shared Marivo skill entrypoints for agents that read `.agents/skills`.
`.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`	Compatibility skill entrypoints 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.

The result is a ready-to-author project:

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

To load semantic-layer packages managed in other repositories, add their authored models/ directories to marivo.toml:

[semantic]
layer_paths = [
  "../sales-domain/models",
  "/opt/company/finance-domain/models",
]

The current project’s models/ directory is always loaded first. Relative paths are resolved from the directory containing marivo.toml; absolute paths are used as-is. Each external models/ root must contain both datasources/ and semantic/. Datasource names, domain names, and semantic IDs must be globally unique across all roots; duplicates cause a load error. marivo doctor, semantic previews, verification, and analysis sessions use these configured layer datasources when resolving semantic objects.

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

Local usage telemetry

Marivo records local usage telemetry as OpenTelemetry-shaped JSONL under the project state directory:

.marivo/telemetry/events.jsonl

Telemetry is local-only: Marivo does not upload these events. Events cover marivo init, analysis intents, discover/transform helpers, and escape-hatch promotions. Records include low-cardinality metadata such as the event name, intent family, status, duration, error class, and analysis session id. They do not include SQL text, datasource hosts, credentials, metric ids, dimension ids, session names, session questions, or frame data.

Disable local telemetry for a process with:

MARIVO_TELEMETRY=off marivo init

Set the project default in marivo.toml:

[telemetry]
enabled = "off" # "on" or "off"

MARIVO_TELEMETRY=on|off overrides the project setting for the current process. If neither is set, local telemetry defaults to "on".

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__)"