magus v0.4.3 is out. See what's new
¶ View markdown source · ✎ Suggest an edit
3 min read

mise

magus installs through mise with no plugin, via its ubi backend, which pulls the GitHub release asset matching your platform:

# The hosted docs substitute the latest release tag below; on GitHub it reads
# literally - get the real value from https://github.com/egladman/magus/releases
mise use -g ubi:egladman/magus@v0.4.3

Pin it per repository by putting it in that repo's mise.toml instead:

[tools]
"ubi:egladman/magus" = "v0.4.3"

Three things to know before choosing this route.

mise owns the version, not magus self update. Upgrade with mise upgrade. Running magus self update on a mise-managed install would replace a binary mise believes it controls, and the next mise install would undo it.

Nothing verifies the release signature. ubi fetches the asset over HTTPS and trusts GitHub; it performs no signature or checksum check of its own. The platform installers and magus self update both verify the artifact against the Ed25519-signed manifest. If that guarantee matters, verify the release by hand afterwards, or use the platform installer instead.

You may get a different binary than the installer hands you. The installer defaults to the static build; ubi resolves to the dynamically linked one where a release publishes both. darwin/amd64 currently ships only a static build, so that is what it gets there.

Why not aqua, or the go backend?

aqua is mise's preferred backend where a tool is registered, and it is the better target long-term because the aqua registry carries checksum and signature metadata that ubi has no equivalent for. It is not usable yet: magus has no aqua-registry entry, so aqua:egladman/magus fails with no aqua-registry found. Getting one is an upstream pull request to aquaproj/aqua-registry, and it would close the verification gap above.

The go backend does not currently work at all. It is documented here because people find it anyway, not because it is supported.

Not the golden path, and not a route to adopt. magus is a build tool, and a build tool installed through the package manager of a toolchain it manages puts a circle in your foundation: you need a working Go toolchain to obtain the thing you use to manage Go builds, and when something breaks the remedy is to upgrade the toolchain you were using magus to pin. Those failures are oblique, hard to guard against, and there is usually nowhere sensible to attach an error message explaining what happened. The same objection applies to installing any build tool with npm, cargo, or pip. Use the install script.

# fails outright, before it ever reaches a compile step
mise use -g go:github.com/egladman/magus/cmd/magus@latest

go.mod requires github.com/egladman/magus/libs/diagnostics and .../libs/gopherbuzz (nested modules with their own go.mod) at v0.0.0, resolved only through this repo's own LOCAL replace directives; neither nested module has ever had a tagged release. go install pkg@version (what the go backend runs under the hood) refuses outright to build any module whose go.mod contains a replace directive, local or not, unless that module is the main module of the build, so the install dies on the replace directives themselves, before dependency resolution or compilation ever starts. There is no flag that gets around this from the consuming side; it is fixed only by the nested modules getting real tags, at which point the require lines above would point at a real version and the replace directives could be dropped for a downstream install.

Even if that were fixed, go install still cannot pass the -ldflags that stamp the version, commit, and build date; a go-backend install would present itself to magus as unknown (unknown) built unknown, the dev-build sentinel magus keys on internally to fingerprint an unstamped build, rather than the release it came from.

SetupInstall magus from a signed release, verify it, set up your shell, and keep it current with magus self update. SpellsA spell is a library of tool-native ops (go-build, cargo-clippy, eslint) plus cache metadata that your magusfile composes into runnable targets. ChangelogEvery change to magus, newest first, in Keep a Changelog format, starting with the unreleased entries. Generated from changes/unreleased/ and releases/*.yaml. Cache modelHow magus computes a content-addressed cache key from a target's declared inputs, replays outputs on a hit without rerunning the body, and stores it all as plain files every checkout of the repository shares.
miseubiaquapackage-managergo-install
Last updated (7b7a69bb)
Glossary

Target

A named operation (build, test, ...) you invoke with magus run <target>; it may compose a spell's tool-native operations and depend on other targets. Target in full.

Op

A single tool-native command a target composes (long form: operation); the middle of the work hierarchy (Spell to Op to Target). Op in full.

Manifest

The file that declares what a package is: its name, dependencies, entry points and tool config (go.mod, package.json, pyproject.toml, Cargo.toml). How the workspace builds, tests and lints the package belongs in the magusfile, not in the manifest's scripts. Manifest in full.

Ward

A coded diagnostic that inspects a resolved op and nudges or blocks an anti-pattern before it runs. Ward in full.

Module

A magus stdlib namespace a magusfile imports for host capabilities: filesystem, exec, vcs, and more. Module in full.

Buzz

The language magusfiles are written in (the .buzz engine). Buzz in full.

CI

An ordinary target you compose yourself with ctx.needs; magus does not hardcode its stages. It is the anchor magus affected ci keys off, and ci strips the rw charm. CI in full.

Tool

An action a model can call through its host: a name, a description, a typed input and a result. magus serves its tools over MCP, each a read of the workspace model or a run of the CLI it already has. Tool in full.

Run

One target executing under one magus invocation, such as magus run test web or magus affected ci. A run keeps its captured output behind an output reference. Every magus run is a run whether or not any job asked for it; see Job for how the two relate. Run in full.

Lease

The grant a holder takes on a job: the write and read paths that job declared, enforced in the checkout that took it with magus job exec. A job is the piece of work; a lease is permission over it. Lease in full.

Conventions

This page uses none of the site's convention markers. The full set is on the conventions page.