Quickstart

You need uv and Docker Engine 28 or newer.

1. Install the CLI

uv tool install metrics-book

This installs mb. Every command takes --json, and mb --help --json lists every command, flag and refusal code.

2. Make a project

mb init acme_metrics
cd acme_metrics

mb init makes a new project repository: its folders, stack.yml, compose.yml and AGENTS.md. stack.yml pins the project to this version of the core, with the duckdb warehouse and the sops secrets provider. The folder becomes a Git repository with the project as its first commit.

Add --dry-run --json to see every file it would write, as a diff, before it writes anything.

3. Start from the e-commerce template

mb templates install ecommerce

This copies the e-commerce template into the project: a sample data source in pipelines/, the dbt models, the metrics and the reports. The data is sample data, labelled as such everywhere it is copied. templates.lock.yml records the hash of every file, and mb templates remove ecommerce takes it all out again.

4. Run the stack

mb dev up

This starts the whole stack in Docker on your machine, with sample data and a development sign-in. It prints two URLs: the preview of the web app and the MCP connector. Put the connector’s port in .mcp.json for Claude Code, .codex/config.toml for Codex or .cursor/mcp.json for Cursor, and your agent can query the metrics.

Stop the stack with mb dev down. mb dev reset also throws the data away.

Next steps

Core and projects explains what lives in your project and what comes from the core.
Metrics shows how a metric is defined and described.
How to deploy says where to run it and which servers we recommend.
Commands lists everything mb does today.