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

Install on Windows

Warning

Nothing has run these binaries end to end. Both Windows targets are built by the release pipeline and never executed by it: windows/amd64 compiles and links natively, windows/arm64 is cross-compiled and is the newest, least proven target of all. windows/amd64 has shipped for several releases and has field use behind it; windows/arm64 has none.

The Buzz JIT is also newly enabled on Windows and its machine-code path has never run on a Windows machine here. If a magusfile gives a result that looks wrong, set BUZZ_JIT=0 and re-run: if the answer changes, that is a JIT bug and a very valuable report.

See platform support for the full matrix.

magus ships as a single self-contained binary. Download it with curl.exe, extract it into a PATH directory you own, then verify it before first run. Run these in PowerShell:

Quick install

# 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
$VERSION = "v0.4.3"
$ARCH = "amd64"       # or arm64 on Windows on ARM
curl.exe -fLO "https://github.com/egladman/magus/releases/download/$VERSION/magus_${VERSION}_windows_${ARCH}_static.tar.gz"
mkdir -Force $Env:USERPROFILE\bin | Out-Null
tar -xzf "magus_${VERSION}_windows_${ARCH}_static.tar.gz" magus.exe
Move-Item -Force magus.exe $Env:USERPROFILE\bin\magus.exe
magus version

The archive also carries LICENSE, THIRD-PARTY-NOTICES, README.md, and a BUILDINFO file naming the exact version, commit, platform, and variant. Naming magus.exe on the tar line above extracts just the binary; drop it to unpack all of them. BUILDINFO is readable without running anything, which is the point if a dynamically linked build will not start.

Both curl.exe and tar ship with Windows 10 (1803+) and Windows 11, so no extra tooling is needed. $VERSION above is the current release; GitHub Releases lists every build.

To fill in $ARCH from the machine rather than by hand, $Env:PROCESSOR_ARCHITECTURE reads AMD64 or ARM64:

$ARCH = if ($Env:PROCESSOR_ARCHITECTURE -eq "ARM64") { "arm64" } else { "amd64" }

Testing status

Windows binaries are built by the release pipeline but are not executed by CI, which runs on Linux only. windows/amd64 has shipped for several releases and has field use behind it; windows/arm64 is new and has never been run end to end.

The Buzz JIT is also newly enabled on Windows (it was disabled there until this release line) and its generated machine code has not executed on any Windows machine during development. If a magusfile gives a result that looks wrong, re-run with the JIT off:

$Env:BUZZ_JIT = "0"
magus run <target>

If the answer changes, that is a JIT bug rather than a magusfile bug, and it is a very useful thing to report. See Platform support.

Which archive

The _static archive above is what both architectures ship, and it is what magus self update fetches. No dynamically linked archive is published: on Windows it would link the MSYS2 mingw copies of libzstd/liblzma, which a user's machine has no reason to carry. magus run release-build:dynamic produces one from source if you want it.

Verify the download

Fetch the manifest and its signature next to the tarball:

curl.exe -fLO "https://github.com/egladman/magus/releases/download/$VERSION/SHA256SUMS"
curl.exe -fLO "https://github.com/egladman/magus/releases/download/$VERSION/SHA256SUMS.sig"

Then verify the Ed25519 signature first, and only then the checksum: checking a hash against an unverified manifest proves nothing. The exact commands are in Verify a release.

Put it on your PATH

If magus version is not found, add the install directory to your user PATH (persists across sessions):

[Environment]::SetEnvironmentVariable("Path", "$Env:USERPROFILE\bin;$Env:Path", "User")

Open a new PowerShell window afterward, then re-run magus version.

Next steps

SetupInstall magus from a signed release, verify it, set up your shell, and keep it current with magus self update. Knowledge graphThe knowledge graph is a deterministic, cache-backed graph of the magus domain (projects, targets, spells, ops, charms, modules, diagnostics, docs, and buzz sources) that agents and humans query instead of grepping. This page covers the schema, the verbs, the file layout, and how to point external graph tools at an export. 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 under .magus.
downloadinstallwindowspowershellpath
Last updated (895d94e4)
Earlier changes on this page (4)

Full history ↗ · Blame source ↗

Glossary

Magusfile

The magusfile.buzz that declares a project's targets (as export funs) and binds its spells. See targets.

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.

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

Ward

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

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.

Session

An agent host's conversation, by the id the host delivers to its hooks. magus never mints one: a record with no session is unattributed, and the OS user it carries says whose account ran it.

Window

The terminal a command runs in. It keys fire-once notices for a caller no host gave a session, and is never recorded as a session.

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.

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.

Conventions

Admonitions

Call-outs are rendered from GitHub-style alert blockquotes and carry a colored accent per type:

Note

Context worth knowing, but not a warning.

Warning

Something that can bite you if ignored.

The types are NOTE, TIP, IMPORTANT, WARNING, and CAUTION.