Skip to content
Metrics Book
Not released yet: version 0.1 is being built. See what works today.

Commands

mb is the command line for a Metrics Book project. It makes a project, checks and formats it, sets its brand, manages its secrets, installs templates and runs the whole stack on your machine in Docker. It is built for agents first, so it never asks a question and every answer can be read as JSON.

The CLI is not on PyPI yet.

What every command shares

Section titled “What every command shares”

Every command takes --json. With it, the command prints one JSON document to stdout and nothing else. The shape of that document is on the output page.

Exit codes:

  • 0: done.
  • 1: refused, or a check failed.
  • 2: used wrongly (flags that conflict, or no project or repository to run in).

mb --help --json prints every command, its flags and arguments, an example, and the refusal codes each command can return. An agent can read that one document instead of running --help on each command. The codes themselves are listed on the refusal codes page.

Commands that change files also take --dry-run: check, show the change as a diff, and write nothing. They are marked below.

Commands without a group

Section titled “Commands without a group”

These four run on a project or a repository as a whole.

Command What it does Flags
mb build Build the project’s four images, api, jobs, anfra and cerbos, with Docker. --core
mb check Run the format checks, linters, types and tests for the areas a change touched. --staged, --all, --e2e
mb fmt [PATHS...] Format Python with ruff, dbt SQL with sqlfmt, and the rest with prettier. --check, --dry-run
mb init PATH Make a new project: its folders, stack.yml, compose.yml and AGENTS.md. --name, --dry-run

Flags:

  • --core PATH: a checkout of the Metrics Book core to build the core’s images from, instead of the release this project’s stack.yml pins.
  • --staged: check the staged files instead of the branch’s changes.
  • --all: check every file in the repository and add the security scanners.
  • --e2e: also run the end-to-end test, mb dev up on examples/ecommerce, on duckdb and on postgres. Needs Docker and the core’s checkout.
  • --check: write nothing and fail if any file needs formatting.
  • --name NAME: the project’s name, which names its images and its secrets keys. Snake_case, up to 40 characters. Defaults to the folder’s name in snake_case.

brand

Section titled “brand”

Set the product’s name, logo, mark, icons, typeface and locale.

Command What it does Flags
mb brand show The brand as resolved, with where each value comes from. none
mb brand check Run only the brand and palette checks, each with the number it measured. none
mb brand preview Write a page of every icon, the logo and mark, a report header and the sign-in card, and open it. With --png, write screenshots an agent can read. --png DIR
mb brand apply DOCUMENT Set the whole brand from one document, all of it or none of it. --dry-run
mb brand name VALUE Set the product name. --dry-run
mb brand logo FILE Check and copy the full logo into brand/. --dark FILE, --dry-run
mb brand mark FILE Check and copy the square mark into brand/. Every icon is made from it. --dark FILE, --dry-run
mb brand accent COLOUR Set the accent: writes palettes/<project>.yml and names it in stack.yml. --dark COLOUR, --dry-run
mb brand palette NAME Name the palette the product uses. --dry-run
mb brand font [VALUE] Set the typeface; without a name, list the choices. --dry-run
mb brand locale VALUE Set how numbers and dates read. --currency, --week-starts, --dry-run
mb brand reset [PART] Return a part of the brand, or all of it, to the default. --dry-run

Flags:

  • --png DIR: write light and dark screenshots here instead of opening the page.
  • --dark: the variant for dark mode. For accent, the accent for dark mode, derived when left out.
  • --currency CODE: an ISO 4217 code, like DKK.
  • --week-starts DAY: the first day of the week.

dev

Section titled “dev”

Run the whole stack on this machine, in Docker.

In a project, dev runs the core’s images at the version stack.yml pins. In the core’s checkout, it builds them and runs examples/ecommerce. The compose project name and the api’s port come from a hash of the project’s path, so several checkouts run side by side.

Command What it does Flags
mb dev up Build the images and start the stack, with the dev sign-in on and sample data. --core
mb dev down Stop the stack and remove its containers. The database and the data stay. none
mb dev reset Stop the stack and throw its data away: the database, the marts, the build. none
mb dev logs SERVICE Show the last lines a service wrote. --tail

Flags:

  • --core PATH: a checkout of the Metrics Book core to build the core’s images from, instead of the release this project’s stack.yml pins.
  • --tail N: how many of the last lines to show. The default is 200.

secrets

Section titled “secrets”

List, show, set, copy, run with and generate the core’s secrets and those in secrets.yml. It never prints a value.

Command What it does Flags
mb secrets init Make the age keys, sops rules and container files the sops provider needs. --keys-dir
mb secrets list Show every name stack.yml needs, the core’s and secrets.yml’s, per container. none
mb secrets show NAME Show a secret: its description, containers, hint, set date and rotation due date. none
mb secrets check Fail unless every required name is set for every container that uses it. none
mb secrets set NAME Take a secret’s value from a person and write it through the provider. --container, --from-clipboard, --no-browser
mb secrets copy NAME Put a secret’s value on the clipboard for the person to paste elsewhere. --container
mb secrets generate [NAME] Make a random value for a name marked generate and write it. --missing, --rotate
mb secrets run --only NAMES -- COMMAND... Run one command with the named secrets in its environment and no others. --only (required)

Flags:

  • --keys-dir PATH: where to write the keys. The default is ~/.config/metrics-book/age/<name in stack.yml>.
  • --container NAME: for set, set it for this container only (the default is every container that uses it). For copy, copy this container’s value.
  • --from-clipboard: take the value from the clipboard and clear it.
  • --no-browser: print the entry page’s address, don’t open it.
  • --missing: every generate name that is not set.
  • --rotate: replace a value that is already set.
  • --only NAMES: the names from secrets.yml to give the command, comma separated.

mb secrets run exits with the exit code of the command it runs, as env and uv run do. With --json that code is in an exit_code field and refusals is empty. Refusals from mb itself, made before the command starts, exit 1 or 2 and fill refusals. The output and errors of the command have every value redacted.

skills

Section titled “skills”

The third-party agent skills pinned in skills.lock.yml.

Command What it does Flags
mb skills sync [SOURCE] Install the skills skills.lock.yml pins, each where its area is. --update, --yes, --dry-run

Flags:

  • --update: show what the newest commits change; install nothing.
  • --yes: with --update, write the newest commits to the lock.

templates

Section titled “templates”

The templates that ship with this mb: working slices of a setup to copy.

Command What it does Flags
mb templates list List the templates this mb carries. none
mb templates show TEMPLATE_ID Show what a template holds, and where each part lands in a project. none
mb templates guide TEMPLATE_ID Print how a template defines things, for an agent writing similar ones. none
mb templates install TEMPLATE_ID Copy a template into the project, with its sample data. --project, --check, --dry-run
mb templates copy TEMPLATE_ID ITEMS... Copy single items of a template, and print what they are built on. --project, --into, --dry-run
mb templates remove TEMPLATE_ID Delete the files the lock lists for a template, and what install added to the project’s dbt files. --project, --force, --dry-run

Flags:

  • --project PATH: a folder in the project. The default is the working directory.
  • --check: change nothing; exit 1 if an installed file differs from the template or from templates.lock.yml.
  • --into FILE: insert the metrics into this dataset file, a path in the project, instead of only printing them.
  • --force: delete files changed since install too, instead of refusing.