Install Mandately

Set Mandately up on your team's repository in one sitting. For the first week it only watches: it records what your rules would decide beside what your team did, and changes nothing on the board or in git.

Before you start

You need three things.

A machine that stays on for the week

Linux or macOS, with Python 3.11 or newer and git.
Outbound HTTPS to api.github.com and to your Multica server (Multica Cloud is api.multica.ai). Nothing connects in.
git fetch works in the checkout that holds your rules, without a password prompt.
Optional: the GitHub command line, gh, signed in. Mandately then opens the pull request for you.

A GitHub token

It reads contents, pull requests and metadata in every repository in scope. Set it in the shell that runs Mandately, or sign in with gh auth login:

Terminal

export GITHUB_TOKEN=...

GH_TOKEN works too. The person who runs the setup also needs to push a branch to the repository that holds the rules.

A Multica account for Mandately

Add a member account for Mandately to your workspace. The setup lists it among your agents, so what it posts never counts as a person's work. On the machine that runs the watch, sign in as it with the multica command line, or set its token:

Terminal

export MULTICA_TOKEN=...

Set MULTICA_SERVER_URL too, only if you run your own Multica server.

Set up

Install

Answer 6 questions

Run this inside the repository that will hold your rules, usually your main product repository:

Terminal

mand init

It asks:

Which Multica workspace your team uses.
Which GitHub repositories to read, then how you deploy and how your team marks a fix.
Who is accountable for the team's work.
Who else may say release, go and ship.
Which accounts are agents.
Which paths always need the owner's go before a change merges.

When the board connects, it suggests your agents and maps your board's statuses for you.

Merge the pull request

mand init opens a pull request with 2 commits: Mandately's default pack, then your answers. Review the second one and merge it. Nothing runs until you do.

Measure your baseline

Terminal

mand baseline

It reads the last 90 days from git and your board, which takes a few minutes per month of history. Every report compares your week against it.

Start watching

Terminal

mand watch

Its first line says what it reads:

Output

Watching 1 board and 2 repositories. Recording, changing nothing.

Leave it running for the week, and see Keep the watch running to keep it going after you close the terminal.

Read the week

Terminal

mand report

Your week beside your baseline: what merged, what got done and how long it took. Run it any time.

Keep the watch running

mand watch keeps running for the whole week. A pass that fails, for example while the network is down, is tried again on the next one, and each pass starts where the last good one stopped, so nothing is skipped. Pick one of the two ways below.

In tmux

Terminal

tmux new-session -d -s mandately 'mand watch'

It keeps running after you close the terminal. To look at it, run tmux attach -t mandately.

As a systemd service, on Linux

It keeps running after a restart. Do this as the user who holds the credentials.

Create the service file

~/.config/systemd/user/mandately.service

[Unit]
Description=Mandately watch

[Service]
WorkingDirectory=%h/src/your-repo
EnvironmentFile=%h/.config/mandately/env
ExecStart=%h/.local/bin/mand watch
Restart=on-failure

[Install]
WantedBy=default.target

Set WorkingDirectory to your repository's checkout.

Add your tokens

~/.config/mandately/env

GITHUB_TOKEN=...
MULTICA_TOKEN=...

Then make the file readable only by you:

Terminal

chmod 600 ~/.config/mandately/env

Start it

Terminal

systemctl --user enable --now mandately
loginctl enable-linger $USER

The second line keeps it running after you sign out.

What the commands take

command	option	what it does
`mand init`	`--no-push`	makes the branch on your machine only, for a rehearsal
`mand baseline`	`--days`	measures another window than the last 90 days
`mand baseline`	`--replace`	measures again over a baseline already recorded
`mand report`	`--last`	shows last week instead of this one
`mand report`	`--json`	prints the numbers as JSON

Without the GitHub command line, mand init prints the link that opens its pull request. After each pass, mand watch prints one line: events read, how many needed a person's word, and how many differed from your rules.

What a report shows

Your measures beside your baseline: merged changes, issues done, release to done and the others.
Flow: work in progress and the time in each state.
Delivery, once deploys are on the ledger: deploys, change lead time, change fail rate and time to recover.
What your rules said, and where your team and your rules differed.

Where things live

what	where
your rules	`.mandately/` in your repository, read from the main branch
the ledger, the baseline and a copy of the merged rules	`~/.local/share/mandately/<owner>-<repo>/`, or `$MANDATELY_HOME`

For github.com/acme/api, the folder is ~/.local/share/mandately/acme-api/. The ledger is one SQLite file and it is your record: back up its folder. It sits outside the repository, so git clean leaves it alone.

Change a rule

Edit the file in .mandately/ and open a pull request. It needs the owner's go, and the watch uses the new rules from its next pass. Each decision records the version of the rules it read.

Try it first

Rehearse on your machine without touching your main branch. A rehearsal keeps its own ledger, apart from the real one.

Terminal

mand init --no-push
git switch mandately/init
mand watch --once --unmerged --since 2026-11-09
mand report --unmerged

Pick a --since date a few days back. To answer the questions from a file, for a script, see mand init --help.

If Mandately says

Mandately says	What to do
Your rules are not on main yet	Merge the pull request from the setup, then run the command again.
multica: no token	Sign in as the Mandately account with the `multica` command line, or set `MULTICA_TOKEN`.
github: no token	Set `GITHUB_TOKEN`, or sign in with `gh auth login`.
Could not fetch main from origin	Give the machine git credentials that work without a terminal (see Keep the watch running).
A baseline is already recorded	The baseline stays as the reference. To measure it again, add `--replace`.
This repository already has .mandately/ on main	Your rules exist. Change them by pull request.
Your rules have a mistake in ...	The message names the file and the key. Fix it by pull request.

Update

Terminal

pipx upgrade mandately

If it runs as a service, restart it:

Terminal

systemctl --user restart mandately

Remove it

Stop the watch, then uninstall:

Terminal

pipx uninstall mandately

Delete the folder under ~/.local/share/mandately/, and remove .mandately/ from your repository by pull request.