# Install

muhar is a single static binary. There are three ways to get it: take it from a release bundle, build it from source, or run it from a clone without installing anything. All three produce the same program.

## Requirements

| Requirement | Why |
|---|---|
| `sh` on `PATH` | muhar runs the spec's `test` command with `sh -c`, so pipes and `&&` work. On Windows this means a POSIX shell such as the one Git for Windows installs. |
| Go 1.25 or later, only to build from source | The module muhar lives in declares `go 1.25.0`. A release binary needs no Go toolchain. |
| `go` on `PATH`, only for some parallel runs | With `-j` above 1, muhar rewrites relative `replace` directives in copied `go.mod` files using `go mod edit`. Only a tree whose `go.mod` contains a `replace` needs it. See [How a run works](internals.md#module-replace). |
| Free space in the temp directory | Each parallel worker gets a full copy of the spec's root; every run gets a throwaway Go build cache. |

## From a release bundle

muhar is built and published with every release of [medici-finance/assay](https://github.com/medici-finance/assay/releases), inside the `desk-tools-<platform>.tar.gz` bundle together with the other desk tools. Bundles exist for `linux-amd64`, `darwin-arm64`, `darwin-amd64`, `windows-amd64` and `windows-arm64`. There is no `linux-arm64` bundle yet; build from source there.

On Linux or macOS, download the bundle and the release's checksum list, verify, and extract only `muhar`. Set `PLATFORM` to match your machine:

```sh
PLATFORM=linux-amd64
BASE=https://github.com/medici-finance/assay/releases/latest/download
curl -fsSLO "$BASE/desk-tools-$PLATFORM.tar.gz"
curl -fsSLO "$BASE/checksums.txt"
grep " desk-tools-$PLATFORM.tar.gz\$" checksums.txt | sha256sum -c -
tar -xzf "desk-tools-$PLATFORM.tar.gz" ./muhar
mkdir -p "$HOME/.local/bin"
install -m 0755 muhar "$HOME/.local/bin/muhar"
export PATH="$HOME/.local/bin:$PATH"
```

On macOS use `shasum -a 256 -c -` in place of `sha256sum -c -`. The check prints `desk-tools-<platform>.tar.gz: OK`; anything else means the download is not the published file, so stop.

The `PATH` change above applies to this shell. Add the same export to your shell's startup file to keep it in future sessions.

On Windows, choose `windows-amd64` or `windows-arm64`. The archive member is `./muhar.exe`; extract that binary, put it in a directory on `PATH`, and keep a POSIX `sh` on `PATH` as described in [Requirements](#requirements). The Unix `install` command above is not a PowerShell recipe.

For CI, pin a release instead of `latest`, so a new release cannot change your gate without a commit:

```sh
BASE=https://github.com/medici-finance/assay/releases/download/v1.0.39
```

The bundle's version is the Assay release tag; muhar has no version number of its own today.

## From source

muhar lives in the `tools/desk` Go module of the Assay repository. Build it from a clone:

```sh
git clone https://github.com/medici-finance/assay.git
cd assay/tools/desk
go install ./cmd/muhar
```

The binary lands in `$(go env GOBIN)`, or `$(go env GOPATH)/bin` when `GOBIN` is unset. Add that directory to `PATH`.

> `go install github.com/medici-finance/assay/tools/desk/cmd/muhar@latest` does not work. The `tools/desk` module uses a `replace` directive that points at another directory of the repository, and the go command refuses `go install module@version` for a module with `replace` directives. Build from a clone as above.

To build a specific release, check out its tag before `go install`:

```sh
git -C assay checkout v1.0.39
```

## Without installing

In a clone of the Assay repository, `go run` compiles and runs muhar in one step. This is how Assay's own CI calls it:

```sh
cd assay/tools/desk
go run ./cmd/muhar -spec /path/to/mutations.json
```

`go run` is a wrapper: it returns 0 when the program succeeds, but a muhar exit of 1 or 2 is reported as shell status **1**. For example, an unknown flag makes the binary return 2; `go run` instead prints `exit status 2` on stderr and returns 1. A broken harness's 2 is also collapsed to 1. See [Go's run documentation](https://pkg.go.dev/cmd/go#hdr-Compile_and_run_Go_program).

Use the released or locally built binary when your script needs the exact [exit codes](output.md#exit-codes). To build without installing into `PATH`:

```sh
cd assay/tools/desk
go build -o ./muhar ./cmd/muhar
./muhar -spec /path/to/mutations.json
```

Invoke the binary directly to preserve muhar's numeric exit status. Compilation errors from `go run` also return nonzero before muhar runs, so read stderr to distinguish them from a muhar failure.

## Check the install

`muhar -h` prints the three flags and exits 0. Running it with no spec is a usage error, exit 1:

```console
$ muhar
muhar: -spec is required
$ echo $?
1
```

Continue with the [worked example](getting-started.md).

## Coming

These are planned and not available yet. They are tracked in the open and listed on the [roadmap](roadmap.md).

- A standalone muhar README and a one-line install that fetches only muhar, not the whole desk-tools bundle ([assay#2638](https://github.com/medici-finance/assay/issues/2638)).
- A reusable CI action that installs muhar, runs a sharded sweep and gates on the result ([assay#2642](https://github.com/medici-finance/assay/issues/2642)).

## Licence

muhar is part of the Assay repository and is licensed under the Apache License, Version 2.0. Source: [tools/desk/cmd/muhar](https://github.com/medici-finance/assay/tree/main/tools/desk/cmd/muhar).

---

Source of this page: https://muhar.assay.guide/install