magus v0.4.2 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.2

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

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

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. magus DocumentationThe magus documentation hub covering install, targets, spells, charms, operations, engines, remote caching, MCP, telemetry, and the interactive playground. 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 released change to magus, newest first, in Keep a Changelog format. Generated from releases/*.yaml.
miseubiaquapackage-managergo-install
Last updated (4f8cc295)
Earlier changes on this page (3)

Full history ↗ · Blame source ↗

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. See targets.

Op

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

Ward

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

Module

A magus stdlib namespace a magusfile imports for host capabilities: filesystem, exec, vcs, and more. See the module reference.

Buzz

The language magusfiles are written in (the .buzz engine). See engines.

CI

An ordinary magusfile-defined target you compose yourself with magus\needs - magus does not hardcode its stages. Magus.RunCI treats it specially only in that it strips the rw charm, it is the anchor magus affected ci keys off, and a selected scope with no project declaring it is a load error rather than a silent no-op. See targets.

Lease

One row of the lease ledger: a piece of work an orchestrating agent handed out, with its goal, the checkpoint it was cut against, and the paths it owns or must not touch. The ledger records; the agent guard is what reads those facts back when grading a write. See doctrine.

Conventions

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