Installation

Marivo requires Python 3.10 or newer.

Choose an installation path

Choose one path. Use the installer for the shortest setup; use manual installation when the project must control its Python environment and datasource dependencies.

Option 1: Use the installer

Enter the directory that will contain the Marivo project, then run:

curl -fsSL https://marivo.io/install.sh | bash

The installer first ensures uv, uses it to install a managed Python 3.10 and create or reuse .venv, installs marivo[duckdb,trino,clickhouse], and runs marivo init in the current directory. It supports macOS, Linux, WSL, and Windows through Git Bash, MSYS2, or Cygwin. MySQL is intentionally not part of the default install; add marivo[mysql] manually after installing its native client prerequisites. On Windows, PowerShell is needed only when the installer must install uv. Continue directly to Verify the installation; do not also follow the manual steps below.

Option 2: Install manually

To control the environment and datasource backends, complete these steps in order.

1. Use uv to create a Python 3.10 or newer virtual environment:

uv venv --python 3.10 --seed
source .venv/bin/activate

On Windows Bash shells, activate it with source .venv/Scripts/activate.

2. Install the extra for the datasource backend the project will use:

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

3. Verify the installed version:

marivo --version

4. Optionally materialize project configuration and agent skill links:

marivo init

When the current working directory is not the project root, use marivo init --project-root <project-directory>.

Marivo does not require this command to run. Without it, the current directory is the default project root, the project name defaults to that directory name, external semantic layer paths default to empty, and local telemetry defaults to on. Authoring and runtime operations create the models/ and .marivo/ subdirectories they need.

marivo init is idempotent: it leaves existing files untouched and reports them as skipped, so it is safe to re-run after an upgrade. Re-running adds only what is missing. Use marivo init --force to delete the generated artifacts 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 symlinks: if the platform cannot create a symlink, init prints a warning and continues.

What the agent can use

Path	Purpose
marivo.toml	Optional manifest for overriding project defaults.
models/	Datasource and semantic declarations, created when first authored.
.marivo/	Project-local sessions, evidence, telemetry, and cached metadata, created on first state write.
.agents/skills/	Links to the marivo-semantic and marivo-analysis skills for compatible agents.
.claude/skills/	Links to the same skills for Claude Code.
.codex/skills/	Links to the same skills for Codex.

After marivo init, the optional scaffold has this shape:

your-project/
  marivo.toml
  models/
  .marivo/
  .agents/skills/
  .claude/skills/
  .codex/skills/

Verify the installation

After installation, give the agent this bounded preparation request:

Check this Marivo project’s effective configuration and tell me what is missing before I use its existing semantic layer or create a new one. For credentials, check only environment-variable names and configuration status. Do not request, display, or commit credential values.

This separates project setup from access to business data and from decisions about business meaning.

When an agent is launched by another runtime, prefer the project interpreter selected by that runtime. For a conventional project-local installation, prefer .venv/bin/python on macOS, Linux, and WSL, or .venv/Scripts/python.exe on Windows. Use the selected interpreter to run <selected-python> -m marivo doctor and for subsequent help and execution.

What to review before continuing

Before continuing, confirm that:

• the intended Doctor project root is selected; --project-root takes precedence over MARIVO_PROJECT_ROOT, and without either Doctor uses the current directory without searching ancestor manifests;
• any existing marivo.toml is valid; a missing manifest uses defaults;
• agent skill paths are available when the selected host depends on filesystem skill discovery; run marivo init to install them when needed;
• the required datasource backend extra is installed; and
• credentials are supplied through approved environment-backed fields, not committed as plaintext in project files.

When those checks pass, continue to Quick Start and choose whether to reuse an existing semantic layer or create one. After the selected project path is ready and its business meaning is approved, continue to the first analysis.

A project with none of marivo.toml, models/, or .marivo/ is a valid empty starting point. Doctor reports the effective defaults and missing authored/state directories as informational or skipped checks without creating local state or telemetry. Explicit invalid configuration, layer-path, backend, and credential problems remain diagnostic failures or warnings.