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

magus-describe

Define a magus concept and list its entities

Synopsis

magus describe <noun> [<name>] [flags]

Description

Define a magus concept and list every entity of that kind. The noun is one of spell, charm, target, project, workspace, module, mcp-tool, tool, file, graph, or harness; singular and plural are interchangeable. Pass a name after the noun to detail a single entity instead of listing them all. (The knowledge graph lives under magus graph: export for the merged graph, stats for its shape.)

The charm noun is the inverse of a target ref: "describe charm rw" lists every target that declares the rw charm and the argv edit each one makes, the transpose of the charms a single "describe target" lists.

For a target ref (e.g. "api:build", or ":test" for all projects) magus prints the fully-evaluated dispatch plan: the workspace-rooted source and output globs, the spells that fire, the charm-applied command, and any per-target policy. A target that composes others also prints a "chain" line naming them in invocation order (e.g. "generate -> lint -> build -> test"), read from the ctx.needs calls in the magusfile; a cross-project step reads as "project:target". It lists DIRECT steps only, so a step that itself composes is described by its own ref. Add a charm and --explain (e.g. "lint:rw --explain") to see each charm reshape the command one step at a time.

describe target options

--against ref
With --cache: diff the live key inputs against the stored lines behind an output `ref`
--cache
Show the live cache key, the ref a run would print, the component classes behind it, and what moved since the last recorded run
-e
Short for --explain
--explain
For a ref with charms: show the per-charm argv trace (base then each charm)
--inputs
With --cache: list every key input line, so you can confirm a declared file was actually hashed
--no-default-charms
With --cache: ignore magus.yaml default_charms when keying, matching a run made the same way (CI)

describe projects options

-e
Short for --evaluated
--evaluated
Print workspace-rooted globs, effective claims, and per-target policies

describe spells options

--versions
Probe each spell's tools and report the versions that would key a run

Subcommands

targets
List every target the workspace defines
job
Print one job's terms: its criteria, paths, check and dependencies
target
Detail one target ref: its dispatch plan, globs, spells and policy
projects
List the workspace's projects
project
Detail one named project; takes the same flags as projects
spells
List the spells the workspace resolves
charms
List charms and the targets that declare them
workspaces
List the workspaces registered in config
modules
List the Buzz host modules a magusfile can import
mcp-tools
List the tools the MCP server exposes
tools
List the external tools the workspace's spells require
file
Classify paths as generated output, declared source, maintained, or unclaimed
graph
Emit the target catalog and dependency graph
rules
List the guard rules this workspace enforces, and what each one catches
rule
Detail one guard rule, by the name a verdict reported
harness
Print the host config a wired harness needs and the command you run to merge it

Examples

List every target

magus describe targets

Print what every wired harness needs merged

magus describe harness

One harness's exact fragments, for review or your own merge

magus describe harness <id> -o json

List what the guard enforces

magus describe rules

Look up the rule a verdict named

magus describe rule stage-all

List a charm's declaring targets

magus describe charm rw

Detail one project

magus describe project api

Preview a charm-applied command

magus describe target lint:rw

Trace how each charm reshapes the command

magus describe target --explain lint:rw,debug

See Also

magus(1), magus-ls(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-job(1), magus-notes(1), magus-diff(1), magus-server(1), magus-broker(1), magus-mcp(1), magus-buzz(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. SpellsA spell is a library of tool-native ops (go-build, cargo-clippy, eslint) plus cache metadata that your magusfile composes into runnable targets. 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/cli/registry.goclimagus describespellcharmtargetprojectworkspacemodulemcp-tooltoolfilegraphharnessintrospection
Last updated (c3d601b8)
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.

Project

A directory magus recognizes as a unit of work (it has a magusfile); the unit of caching, scheduling, and dependency tracking. 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.

Charm

An execution modifier attached with : (lint:rw) that changes how a target runs, not which one; the built-in rw flips a check-only target to mutate in place, and ci always strips it. See charms.

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.

Cache

The content-addressed store magus consults before running a target, so unchanged work is skipped. See cache.

Affected

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

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.

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.

Trace

OpenTelemetry's name for one whole magus invocation; every target it runs is a span beneath it. See telemetry.

Knowledge graph

The queryable graph of a workspace's spells, targets, docs, and code relationships; query it with magus query/explain/path. See knowledge.

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.

Invocation

One magus process's recorded facts (the targets it finished, their outcomes, the lease it acted as, and the session it ran in when a host delivered one), kept in a repo-scoped store every worktree shares. magus session lists them; the store prunes itself by last-fact age.

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.