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

Install on macOS

Note

Neither macOS target is covered by CI. darwin/arm64 is the primary development platform, so the suite runs against it constantly by hand. darwin/amd64 is built natively on an Intel runner, so it compiles and links, but is never executed.

See platform support for the full matrix.

magus ships as a single self-contained binary. Download it with curl, extract it into a PATH directory you own (no root, no sudo), then verify it before first run.

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
ASSET=magus_${VERSION}_darwin_arm64_static.tar.gz       # Apple Silicon
# Intel Macs:
#   ASSET=magus_${VERSION}_darwin_amd64_static.tar.gz
curl -fLO "https://github.com/egladman/magus/releases/download/${VERSION}/${ASSET}"
mkdir -p ~/.local/bin
tar -xzf "${ASSET}" magus
mv magus ~/.local/bin/
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 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 does not start.

${VERSION} above is the current release. The _static archive is the installer default and what magus self update fetches.

Verify the download

Fetch the manifest and its signature next to the tarball:

curl -fLO "https://github.com/egladman/magus/releases/download/${VERSION}/SHA256SUMS"
curl -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 (macOS uses shasum -a 256) are in Verify a release.

OpenSSL 3

Both the install script and the manual openssl pkeyutl steps above need OpenSSL 3 with Ed25519 support. Stock macOS ships LibreSSL as /usr/bin/openssl, which does not have it, so signature verification fails with OpenSSL 3 with Ed25519 support is required to verify releases until a real OpenSSL 3 is ahead of it on PATH:

brew install openssl@3

Homebrew does not link openssl@3 onto PATH by default (it would shadow the system one); either add its bin directory ahead of /usr/bin in your shell rc, or invoke it explicitly as $(brew --prefix openssl@3)/bin/openssl for the verification commands in Verify a release.

Clear the quarantine flag

If macOS blocks the binary ("cannot be opened, unidentified developer"), strip the quarantine attribute Gatekeeper added on download:

xattr -d com.apple.quarantine ~/.local/bin/magus

Put it on your PATH

If magus version prints command not found, the install directory is not on your PATH. Add it once, in your shell rc:

# zsh (default) or bash: append to ~/.zshrc or ~/.bashrc
export PATH="$HOME/.local/bin:$PATH"

Open a new shell 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. Install on WindowsDownload, verify, and install the magus binary on Windows (amd64 or arm64) with PowerShell and put it on your PATH. miseInstall magus through mise via the ubi backend, and why the aqua and go backends are not the route to take. 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.
downloadinstallmacosapple siliconquarantinepath
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.

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.

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

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.