magus v0.4.3 is out. See what's new
¶ View generated markdown
3 min read

magus-buzz

Run a Buzz script

Synopsis

magus buzz [-C dir] [file...|-|lsp] [flags]

Description

Run Buzz source from a REPL, a file, stdin, or an inline snippet.

With no argument on a terminal it opens a REPL with the magusfile at the current directory loaded, its targets and bindings ready. A piped or redirected stdin runs as a script instead. In both, the Buzz stdlib, every magus host module (fs, os, http, markdown, and the rest), and the magus namespace are available, so a one-off script needs no dependency install.

A script run inside a workspace runs under that workspace's sandbox policy, the same one a target gets, so its file, process and network access is governed identically and a refusal is recorded on the activity trail.

Parsing is upstream-strict by default: a file written for the magusfile engine needs --embedded, or it fails on rules upstream Buzz enforces and magus does not. The most common one is "argument N must be labeled".

-t runs a file's test blocks and reports pass or fail, which is how Buzz code in this ecosystem is tested. --coverprofile writes an LCOV report for the file under -t (entry file only; imports are measured when they are the -t subject). The lsp subcommand speaks the Language Server Protocol over stdio for an editor integration.

--check parses and type-checks the named files and does not run them, which is the only way to judge a script whose whole job is a side effect: a hook that reads stdin and shells out cannot be validated by running it. It takes several paths, reports every diagnostic rather than stopping at the first, and fails only on errors; warnings print and pass. Resolving a file import still executes that module's top level, since there is no check-only import pass.

It cannot resolve magus/spell/*, which the workspace loader binds, so a magusfile or a target definition reports an unresolved import. Those are the files magus already checks by loading them; --check is for the ones nothing loads.

-C changes the working directory first, in every mode, so one command line runs the same from any directory: magus buzz -C "$ROOT" -s hooks/guard.buzz.

Options

-C dir
Change to dir before anything else, as go -C does, so script paths and imports resolve from it; lsp takes it only as the first flag
--check
Parse and type-check the named files without running them; report every diagnostic
--coverprofile -t
Write an LCOV coverprofile for the file under -t (requires `-t`)
-e code
Execute code given on the command line instead of a file
--embedded
Relax upstream strictness (top-level statements, optional argument labels) to match the magusfile engine
--no-autoload
Start the REPL without executing the magusfile
--profile
Print where compile and import time went, after the script runs
--record magus query output <ref>
Keep what the script printed in the output store and print its ref, so a plan or a review can cite the run (magus query output <ref> reopens it)
-t
Run the file's test "..." {} blocks and report pass/fail
--test
Alias for -t

Subcommands

lsp
Language server over stdio (LSP)

Examples

Open a REPL with the magusfile loaded

magus buzz

Run a script

magus buzz scripts/report.buzz

Run an inline snippet

magus buzz -e 'import "std"; fun main() > void { std\print("hi"); } main();'

Run a file's test blocks

magus buzz -t scripts/report.buzz

Check files without running them

magus buzz --check scripts/report.buzz scripts/build.buzz

Run a magusfile-style file

magus buzz --embedded scripts/target.buzz

Write an LCOV coverprofile while testing

magus buzz -t --coverprofile=out.lcov scripts/report.buzz

See which imports a script spends its time on

magus buzz --profile scripts/report.buzz

Run a probe and keep its output to cite

magus buzz --record probes/does-the-key-move.buzz

Run a root-relative script from any directory

magus buzz -C ~/src/app scripts/report.buzz

See Also

magus(1), magus-ls(1), magus-describe(1), magus-where(1), magus-run(1), magus-affected(1), magus-x(1), magus-clean(1), magus-shell(1), magus-query(1), magus-refs(1), magus-explain(1), magus-path(1), magus-graph(1), magus-diff(1), magus-vcs(1), magus-session(1), magus-job(1), magus-notes(1), magus-queue(1), magus-watch(1), magus-events(1), magus-server(1), magus-broker(1), magus-mcp(1), magus-status(1), magus-spell(1), magus-agent(1), magus-init(1), magus-doctor(1), magus-config(1), magus-completion(1), magus-man(1), magus-self(1), magus-version(1)

ManpagePages in this section. 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. ADR 0003: running an invocation on another operating systemWhether magus should learn to run an invocation on a kernel other than the host's, so a macOS checkout can reproduce a Linux-only failure (landlock, /proc, the unix socket path limit) before CI does. Decides one Engine-API client reached through one user fact, a top-level --platform flag that relays the whole invocation, and symbol indexers that always run from their spell's image; records the prefix script and the provider-spell flag as considered; lists what the reviewers found and how each finding is answered.
generatedinternal/commands/registry.goclimagus buzzbuzzscriptingrepllsp
Last updated (29d8b3de)
Earlier changes on this page (7)

Full history ↗ · Blame source ↗

Glossary

Workspace

The magus root directory that owns a set of projects and shared config; the unit magus operates over. Workspace in full.

Magusfile

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

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.

Spell

A language/runtime adapter (e.g. go, md) that maps generic targets onto a toolchain's real commands. Spell 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.

Engine

The interpreter a magusfile runs on; magus embeds the Buzz engine. Engine in full.

Affected

The set of projects touched by a change; magus affected <target> runs a target only over them. Affected in full.

Sandbox

The restricted filesystem and environment a target runs in, so builds stay reproducible and side-effect-free. Sandbox in full.

Broker

The per-user background process that holds this host's capacity: the machine budget every run claims slots from, and the shared services runs keep warm. A run starts it on demand; broker: off in magus.yaml runs without one. Broker 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.

One-off

A single magus invocation that runs a target and exits, using a per-process pool; the opposite of the long-lived daemon or a service. One-off in full.

MAGUS.md

The committed routing index at a workspace root, regenerated from the knowledge graph: it lists every node and points at the exact query for a given question, so it is the entry point an agent reads first. MAGUS.md in full.

Agent

A model working through an agent host such as Claude Code, Codex, Cursor or OpenCode. magus treats an agent as one more caller of its CLI, MCP tools and console, held to the same checks as a person. Agent in full.

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. Session in full.

Job

The unit of delegated work, and one row of the job store: what an orchestrating agent handed out, with its goal, the checkpoint it was cut against, the paths it may write or must not touch, and the one check it runs. A job's holder is either a session, for work an orchestrator handed out, or the daemon, for its own maintenance. The store records; the agent guard is what reads those facts back when grading a write. Job 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.

Conventions

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