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 [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.

Options

-C string
Working directory for the REPL's import resolution (default: cwd)
--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
-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 Also

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

ManpagePages in this section. ChangelogEvery change to magus, newest first, in Keep a Changelog format, starting with the unreleased entries. Generated from changes/unreleased/ and releases/*.yaml. ScopeThe claim magus is built on - that a correct incremental build already requires a precise model of your repo, and everything else is a read of it. Includes the test for what belongs, the boundaries, and where the claim is strained. SpellsA spell is a library of tool-native ops (go-build, cargo-clippy, eslint) plus cache metadata that your magusfile composes into runnable targets.
generatedinternal/cli/registry.goclimagus buzzbuzzscriptingrepllsp
Last updated (00e25f0e)
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. See workspace.

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.

Spell

A language/runtime adapter (e.g. go, md) that maps generic targets onto a toolchain's real commands. See spells.

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.

Engine

The interpreter a magusfile runs on; magus embeds the Buzz engine. See engines.

Affected

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

Sandbox

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

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

Server

The background process a person starts with magus server start. It serves MCP, the console, background jobs and the warm knowledge graph, and adopts nested magus calls into one pool. See server.

One-off

A single magus invocation that runs a target and exits, using a per-process pool; the opposite of the long-lived server or a service. See server.

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

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.

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 server, for its own maintenance. The store records; the agent guard is what reads those facts back when grading a write. See doctrine.

A job is not a run. magus run build web is a run, and no job exists for it. A job causes runs: its check executes as one, and a server job records the invocation of its last one. Jobs are listed with magus ls jobs and in the console's Jobs view; runs are listed in the Runs view.

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.

Conventions

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